diff --git a/locales/ar/LC_MESSAGES/messages.po b/locales/ar/LC_MESSAGES/messages.po index 79e0de3e8..11b3c5674 100644 --- a/locales/ar/LC_MESSAGES/messages.po +++ b/locales/ar/LC_MESSAGES/messages.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Automatically generated\n" "Language-Team: none\n" @@ -479,6 +479,7 @@ msgid "Deploying Python applications" msgstr "" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -497,6 +498,7 @@ msgid "Incomplete" msgstr "" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -600,7 +602,7 @@ msgid "Unix (including Linux and macOS)" msgstr "" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "" @@ -619,6 +621,141 @@ msgstr "" msgid "Configuration management" msgstr "" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: German `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "Import Package" +msgid "What's an import package?" +msgstr "Paket importieren" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -919,7 +1060,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1058,146 +1199,153 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy msgid "``install_headers``" msgstr "Betreuer" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1205,46 +1353,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1252,26 +1400,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1588,24 +1736,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1614,22 +1766,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1637,7 +1789,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1646,43 +1798,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1774,14 +1926,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Ei" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1789,11 +1942,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "Erweiterungsmodul" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1802,11 +1955,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1815,67 +1968,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "Paket importieren" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Modul" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "Paketindex" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "Pro Projekt Index" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1884,7 +2038,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1892,7 +2046,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1900,21 +2054,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Pures Modul" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1924,48 +2078,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1973,11 +2127,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1986,17 +2140,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2012,12 +2164,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2177,7 +2329,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2246,14 +2398,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2609,8 +2761,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2785,6 +2936,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2793,14 +2952,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2808,36 +2967,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2858,14 +3017,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2905,11 +3064,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2917,7 +3076,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2925,16 +3084,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2944,256 +3103,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3203,78 +3174,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3283,24 +3215,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3309,7 +3241,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3321,13 +3253,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3335,12 +3267,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3348,69 +3280,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3418,42 +3309,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3461,58 +3352,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3520,44 +3411,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3567,17 +3458,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3586,13 +3477,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3602,7 +3493,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3610,21 +3501,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3633,22 +3524,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3656,23 +3547,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3681,11 +3572,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3693,95 +3584,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3789,7 +3680,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3797,7 +3688,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3806,7 +3697,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3816,78 +3707,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3895,7 +3786,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3903,14 +3794,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4024,96 +3907,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4128,9 +4002,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4412,7 +4286,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4517,6 +4391,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4545,7 +4420,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4721,7 +4596,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4780,33 +4655,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4814,146 +4689,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4961,106 +4836,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5510,13 +5385,12 @@ msgstr "Distributionspaket" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5586,7 +5460,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5625,11 +5499,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6248,11 +6122,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6261,19 +6135,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6284,17 +6158,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6302,17 +6176,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6320,7 +6194,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6328,7 +6202,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6337,27 +6211,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6365,11 +6239,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6377,13 +6251,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6391,11 +6265,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6404,21 +6278,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6426,17 +6300,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6448,19 +6322,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6469,13 +6343,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6770,44 +6644,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6815,39 +6697,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6856,52 +6738,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7654,8 +7536,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7772,89 +7654,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7862,129 +7781,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8419,8 +8389,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8431,9 +8401,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8492,13 +8461,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8511,18 +8479,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8531,18 +8499,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8553,42 +8521,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8597,22 +8565,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8620,15 +8588,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8637,14 +8605,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8657,17 +8625,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8675,17 +8643,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8697,17 +8665,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8718,34 +8686,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8753,44 +8721,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8799,18 +8767,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8821,17 +8789,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8839,17 +8807,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8859,17 +8827,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8879,17 +8847,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8899,18 +8867,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8921,18 +8889,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8960,7 +8928,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8979,24 +8947,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9004,21 +8972,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9026,17 +8994,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10409,25 +10377,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10438,86 +10398,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10526,35 +10453,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10562,32 +10489,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10595,41 +10522,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10638,14 +10565,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10653,7 +10580,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10661,33 +10588,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10695,25 +10622,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10724,63 +10651,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10788,71 +10715,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10860,28 +10787,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10890,22 +10817,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10913,29 +10840,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10945,7 +10872,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10953,25 +10880,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10979,85 +10906,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11067,11 +10948,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11080,38 +10961,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11119,7 +11000,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11127,18 +11008,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11147,7 +11028,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11158,7 +11039,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11176,7 +11057,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11185,70 +11066,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11350,41 +11228,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11392,20 +11270,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11413,27 +11291,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11441,19 +11331,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11461,7 +11351,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11469,7 +11359,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11477,31 +11367,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11615,91 +11505,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Betreuer" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11709,11 +11599,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11721,43 +11611,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11765,64 +11655,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11830,13 +11720,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11844,36 +11734,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11882,13 +11772,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11896,20 +11786,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11917,7 +11807,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11927,11 +11817,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11939,7 +11829,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11949,18 +11839,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11969,7 +11859,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11980,63 +11870,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12047,33 +11937,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12082,3355 +11972,3350 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "Betreuer" - -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:186 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 -msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/dependency-specifiers.rst:497 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:8 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:24 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url.rst:29 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:36 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 -msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 -msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 -msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:70 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:73 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:76 +msgid "" +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:95 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:145 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:42 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:51 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:153 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 -msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 -msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "packaging" +msgid "package" +msgstr "Paketierung" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 -msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 -msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:177 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:206 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Dokumentationstypen" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:82 -msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:128 -msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/index.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:151 -msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:56 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "Paketierung" - -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 -msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 -msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:110 +msgid "" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Dokumentationstypen" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Dokumentationstypen" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 -msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:107 +#, fuzzy +msgid "``manylinux``" +msgstr "Betreuer" + +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Dokumentationstypen" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:289 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/platform-compatibility-tags.rst:303 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 -msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:47 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:61 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:81 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:87 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -#, fuzzy -msgid "``manylinux``" -msgstr "Betreuer" - -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:131 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 -msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 -msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 -msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "Betreuer" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15438,7 +15323,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15447,11 +15332,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15462,21 +15347,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15488,7 +15373,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15499,7 +15384,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15511,41 +15396,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15553,7 +15438,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15561,58 +15446,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15620,7 +15505,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15628,13 +15513,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15643,7 +15528,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15652,18 +15537,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15671,7 +15556,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15681,11 +15566,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15693,15 +15578,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15709,11 +15594,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15721,29 +15606,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15752,11 +15637,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15764,14 +15649,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15780,7 +15665,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15914,10 +15799,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16087,22 +15972,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16110,7 +15995,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16118,19 +16003,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16138,24 +16023,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16163,26 +16048,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16190,7 +16075,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16198,63 +16083,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16262,11 +16147,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16275,7 +16160,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16285,7 +16170,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16294,7 +16179,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16302,23 +16187,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16332,7 +16217,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16340,7 +16225,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16352,36 +16237,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16389,21 +16274,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16411,35 +16300,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16447,48 +16336,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16496,7 +16385,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16504,11 +16393,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16516,11 +16405,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16528,20 +16417,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16550,13 +16439,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16566,28 +16455,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16598,14 +16487,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16613,22 +16502,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16637,11 +16526,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16651,11 +16540,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16665,11 +16554,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16677,11 +16566,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16692,11 +16581,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16704,11 +16593,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16716,11 +16605,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16730,11 +16619,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16742,11 +16631,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16754,11 +16643,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16766,11 +16655,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16779,11 +16668,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16792,11 +16681,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16806,7 +16695,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16814,69 +16703,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16884,48 +16773,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16936,7 +16825,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16946,17 +16835,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16965,18 +16854,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16987,7 +16876,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16995,30 +16884,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17026,30 +16915,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17057,60 +16946,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17119,79 +17008,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17200,7 +17089,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17208,31 +17097,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17240,7 +17129,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17249,7 +17138,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17259,14 +17148,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17275,28 +17164,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17305,27 +17194,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17335,7 +17224,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17345,13 +17234,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17570,7 +17459,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17578,7 +17467,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17589,15 +17478,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17605,7 +17494,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17613,7 +17502,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17625,43 +17514,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17670,20 +17559,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18985,28 +18874,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Esperanto `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "kaj enportu la pakon:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -909,7 +1050,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1060,168 +1201,175 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "Jes (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "Jes (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:105 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "Jes (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy msgid "``python setup.py --version``" msgstr "``requires-python``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "Jes (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 #, fuzzy #| msgid "build" msgid "``build``" msgstr "build" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 #, fuzzy msgid "``build_scripts``" msgstr "``description``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 #, fuzzy #| msgid "``pypinfo``" msgid "``dist_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy #| msgid "**easy_install**" msgid "``easy_install``" msgstr "**easy_install**" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 #, fuzzy #| msgid "``pypinfo``" msgid "``egg_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 #, fuzzy msgid "``install``" msgstr "Uzi ``pip`` por instali Pipenv:" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 #, fuzzy msgid "``install_data``" msgstr "Uzi ``pip`` por instali Pipenv:" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 #, fuzzy msgid "``install_egg_info``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy msgid "``install_headers``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 #, fuzzy msgid "``install_lib``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 #, fuzzy msgid "``install_scripts``" msgstr "``description``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 #, fuzzy msgid "``saveopts``" msgstr "``description``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1229,48 +1377,48 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 #, fuzzy #| msgid "pyproject.toml" msgid "Is ``pyproject.toml`` mandatory?" msgstr "pyproject.toml" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1278,26 +1426,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1615,25 +1763,29 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 #, fuzzy msgid "The source distribution (sdist)" msgstr "Fonto-Distribuoj kontraste kun Wheel-oj" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1642,23 +1794,23 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 #, fuzzy msgid "The built distributions (wheels)" msgstr "Fonto-Distribuoj kontraste kun Wheel-oj" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1666,7 +1818,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1675,43 +1827,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1802,14 +1954,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Egg" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1817,11 +1970,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1830,11 +1983,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1843,67 +1996,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Modulo" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Projekto" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1912,7 +2066,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1920,7 +2074,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1928,21 +2082,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Pura Modulo" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1952,48 +2106,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2001,11 +2155,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2014,17 +2168,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2040,12 +2192,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2204,7 +2356,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2273,14 +2425,14 @@ msgid "Column" msgstr "Kolumno" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Priskribo" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Ekzemploj" @@ -2637,8 +2789,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2813,6 +2964,16 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2017-12-01" +msgid "2023-12-14" +msgstr "2017-12-01" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2821,14 +2982,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2836,36 +2997,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2886,14 +3047,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2933,11 +3094,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2945,7 +3106,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2953,16 +3114,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2972,259 +3133,69 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``name``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "``version``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -#, fuzzy -msgid "``url``" -msgstr "``urls``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "``license``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "``classifiers``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "``keywords``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -#, fuzzy -msgid "``project_urls``" -msgstr "``urls``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 #, fuzzy msgid "``packages``" msgstr "``pandas-gbq``" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3234,80 +3205,40 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 #, fuzzy msgid "``install_requires``" msgstr "install_requires" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -#, fuzzy -msgid "``python_requires``" -msgstr "``requires-python``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3316,24 +3247,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3342,7 +3273,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3354,13 +3285,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3368,13 +3299,13 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 #, fuzzy msgid "``scripts``" msgstr "``description``" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3382,70 +3313,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -#, fuzzy -msgid "``console_scripts``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3453,42 +3342,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3496,58 +3385,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3555,44 +3444,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3602,17 +3491,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3621,13 +3510,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3637,7 +3526,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3645,21 +3534,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3668,22 +3557,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3691,23 +3580,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3716,11 +3605,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3728,95 +3617,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3824,7 +3713,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3832,7 +3721,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3841,7 +3730,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3851,78 +3740,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Krei konton" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3930,7 +3819,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3938,14 +3827,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4059,96 +3940,89 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "" +#, fuzzy +#| msgid "Examples" +msgid "Examples:" +msgstr "Ekzemploj" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4163,9 +4037,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4447,7 +4321,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4552,6 +4426,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 #, fuzzy msgid "For example:" msgstr "Ekzemploj" @@ -4581,7 +4456,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4761,7 +4636,7 @@ msgid "Create and activate a virtual environment" msgstr "Krei Virtualajn Mediojn" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4826,34 +4701,34 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 #, fuzzy msgid "Activate a virtual environment" msgstr "Krei Virtualajn Mediojn" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4861,159 +4736,159 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 #, fuzzy #| msgid "Creating Virtual Environments" msgid "Deactivate a virtual environment" msgstr "Krei Virtualajn Mediojn" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 #, fuzzy #| msgid "Creating Virtual Environments" msgid "Reactivate a virtual environment" msgstr "Krei Virtualajn Mediojn" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "Instalo de pakoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "Instalo de pakoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "To install a specific version:" msgid "Install a specific package version" msgstr "Por instali specifan version:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy msgid "Install extras" msgstr "Instalo de pakoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing from other sources" msgid "Install a package from source" msgstr "Instali el aliaj fontoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5021,114 +4896,114 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 #, fuzzy #| msgid "Installing from other sources" msgid "Install from version control systems" msgstr "Instali el aliaj fontoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 #, fuzzy #| msgid "Installing from other sources" msgid "Install from local archives" msgstr "Instali el aliaj fontoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing from other Indexes" msgid "Install from other package indexes" msgstr "Instali el aliaj Indeksoj" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy #| msgid "Requirements files" msgid "Using a requirements file" msgstr "Dosiero requirements.txt" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5588,14 +5463,12 @@ msgstr "Fonto-Distribuoj kontraste kun Wheel-oj" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -#, fuzzy -msgid ":ref:`declaring-build-dependencies`" -msgstr "``dependencies``/``optional-dependencies``" +msgid ":ref:`pyproject-build-system-table`" +msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5669,7 +5542,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5708,11 +5581,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "pyproject.toml" +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6329,11 +6204,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6342,19 +6217,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6365,17 +6240,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6383,17 +6258,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6401,7 +6276,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6409,7 +6284,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6418,27 +6293,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6446,13 +6321,13 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 #, fuzzy #| msgid "Using installed packages" msgid "Legacy namespace packages" msgstr "Uzi instalitajn pakojn" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6460,13 +6335,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6474,11 +6349,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6487,21 +6362,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6509,17 +6384,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6531,19 +6406,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6552,13 +6427,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6856,44 +6731,52 @@ msgstr "Instala dosierformo" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6901,39 +6784,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6942,52 +6825,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7740,8 +7623,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7860,95 +7743,132 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "``version``" + +#: ../source/guides/writing-pyproject-toml.rst:146 #, fuzzy #| msgid "The keywords for the project." msgid "Put the version of your project." msgstr "La ŝlosilvortoj pri la projekto." -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy #| msgid "install_requires vs requirements files" msgid "Dependencies and requirements" msgstr "install_requires kontraste kun requirements.txt" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "``dependencies``/``optional-dependencies``" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "``requires-python``" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 #, fuzzy #| msgid "Creating the package files" msgid "Creating executable scripts" msgstr "Krei dosierojn de la pakaĵo" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7956,130 +7876,182 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "``readme``" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." -msgstr "" +#: ../source/guides/writing-pyproject-toml.rst:311 +#, fuzzy +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "Marklingvo reStructuredText: http://docutils.sourceforge.net/" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "``urls``" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 #, fuzzy msgid "A full example" msgstr "Ekzemploj" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8551,10 +8523,14 @@ msgid "pipx" msgstr "pipx" #: ../source/key_projects.rst:236 +#, fuzzy msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" +"`Cimoj `__ | `GitHub `__ | `PyPI `__" #: ../source/key_projects.rst:240 msgid "" @@ -8565,9 +8541,8 @@ msgstr "" #: ../source/key_projects.rst:247 #, fuzzy msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" "`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `PyPI " @@ -8638,13 +8613,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8657,18 +8631,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8677,11 +8651,11 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 #, fuzzy msgid "" "`Docs `__ | `Issues " @@ -8692,7 +8666,7 @@ msgstr "" "com/pypa/pip/issues>`__ | `GitHub `__ | `PyPI " "`__" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8703,42 +8677,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8747,22 +8721,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8770,15 +8744,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8787,14 +8761,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8807,11 +8781,11 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 #, fuzzy msgid "" "`Docs `__ | :gh:`Issues ` " @@ -8821,7 +8795,7 @@ msgstr "" "pipenv>`__ | `Cimoj `__ | `PyPI " "`__" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8829,17 +8803,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8851,17 +8825,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8872,11 +8846,11 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 #, fuzzy msgid "" "`Docs `__ | `GitHub `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 #, fuzzy msgid "meson-python" msgstr "python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 #, fuzzy msgid "" "`Docs `__ | `GitHub `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8916,28 +8890,28 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy #| msgid "`Source `__" msgid "`GitHub `__" msgstr "`Fonto `__" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 #, fuzzy msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8968,11 +8942,11 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 #, fuzzy msgid "" "`Docs `__ | `GitHub `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8994,17 +8968,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -9012,17 +8986,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -9032,11 +9006,11 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 #, fuzzy msgid "" "`GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -9056,11 +9030,11 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 #, fuzzy msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9080,18 +9054,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9102,11 +9076,11 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 #, fuzzy msgid "" "`Docs `__ | `GitHub " @@ -9117,7 +9091,7 @@ msgstr "" "`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9145,7 +9119,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9164,24 +9138,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9189,21 +9163,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9211,11 +9185,11 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 #, fuzzy msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10599,25 +10573,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10628,86 +10594,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10716,35 +10649,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10752,32 +10685,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10785,41 +10718,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10828,14 +10761,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10843,7 +10776,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10851,33 +10784,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10885,25 +10818,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10914,63 +10847,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10978,71 +10911,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -11050,28 +10983,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11080,22 +11013,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11103,29 +11036,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11135,7 +11068,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11143,25 +11076,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11169,15 +11102,15 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "Vidu" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" @@ -11185,72 +11118,26 @@ msgid "" msgstr "" "http://self-issued.info/docs/draft-jones-jose-jws-json-serialization.html" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "http://self-issued.info/docs/draft-jones-jose-json-private-key.html" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "Komparo al .egg" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "Oftaj demandoj" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11260,11 +11147,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11273,38 +11160,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "Kio temas pri «purelib» kontraste kun «platlib»?" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11312,7 +11199,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11320,18 +11207,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11340,7 +11227,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11351,7 +11238,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11369,7 +11256,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11378,70 +11265,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 -msgid "" -"The rules on escaping in wheel filenames were revised, to bring them into " -"line with what popular tools actually do (February 2021)." +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" +"The rules on escaping in wheel filenames were revised, to bring them into " +"line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "Nomo" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11543,41 +11427,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "Versio" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11585,20 +11469,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11606,27 +11490,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11634,19 +11530,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11654,7 +11550,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11662,7 +11558,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11670,31 +11566,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11808,91 +11704,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Prizorganto" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11902,11 +11798,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11914,43 +11810,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11958,64 +11854,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -12023,13 +11919,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -12037,36 +11933,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12075,13 +11971,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12089,20 +11985,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12110,7 +12006,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12120,11 +12016,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "Malofte uzataj kampoj" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12132,7 +12028,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12142,18 +12038,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12162,7 +12058,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12173,67 +12069,67 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 #, fuzzy #| msgid "Rarely Used Fields" msgid "Deprecated Fields" msgstr "Malofte uzataj kampoj" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 #, fuzzy #| msgid "Requirements files" msgid "Requires" msgstr "Dosiero requirements.txt" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12244,33 +12140,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12279,3393 +12175,3390 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 #, fuzzy msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "Marklingvo reStructuredText: http://docutils.sourceforge.net/" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Specifado" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Specifado" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" -msgstr "``dynamic``" - -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -#, fuzzy -msgid "``gui-scripts``" -msgstr "``description``" - -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "Prizorganto" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 +#: ../source/specifications/dependency-specifiers.rst:132 #, fuzzy -msgid "``optional-dependencies``" -msgstr "``dependencies``/``optional-dependencies``" - -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "Tipo de TOML_: signoĉeno" +msgid "Names" +msgstr "Nomo" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." -msgstr "La nomo de la projekto." +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" +msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Versio" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." -msgstr "La resuma priskribo de la projekto." - -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" -msgstr "Tipo de TOML_: signoĉeno aŭ tabelo" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" +msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:183 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" -msgstr "Tipo de TOML_: tabelo" - -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Versio de Python" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:236 +#, fuzzy +msgid "``os_name``" +msgstr "``name``" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:237 +#, fuzzy +msgid "``os.name``" +msgstr "``name``" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:238 +#, fuzzy +msgid "``posix``, ``java``" +msgstr "``pipenv``, ``nose``" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" -msgstr "Tipo de TOML_: listo de signoĉenoj" - -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." -msgstr "La ŝlosilvortoj pri la projekto." - -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:255 +#, fuzzy +msgid "``platform_version``" +msgstr "``version``" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:256 +#, fuzzy +msgid "``platform.version()``" +msgstr "``version``" -#: ../source/specifications/declaring-project-metadata.rst:277 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:262 +#, fuzzy +msgid "``3.4``, ``2.7``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "``requires-python``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +#, fuzzy +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``2.7.12``, ``3.6.4``" + +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" -msgstr "Tipo de TOML_: listo de signoĉenoj" +#: ../source/specifications/dependency-specifiers.rst:268 +#, fuzzy +msgid "``cpython``" +msgstr "python" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 -msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 -msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/dependency-specifiers.rst:491 +msgid "" +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url.rst:8 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:17 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:24 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:29 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 +#: ../source/specifications/direct-url.rst:36 msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -#, fuzzy -msgid "Names" -msgstr "Nomo" - -#: ../source/specifications/dependency-specifiers.rst:132 -msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url.rst:54 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 -msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 -msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 +#: ../source/specifications/direct-url.rst:62 #, fuzzy -msgid "Versions" -msgstr "Versio" +msgid "``pip install app``" +msgstr "Uzi ``pip`` por instali Pipenv:" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:68 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 -msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Versio de Python" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:58 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -#, fuzzy -msgid "``os_name``" -msgstr "``name``" - -#: ../source/specifications/dependency-specifiers.rst:235 -#, fuzzy -msgid "``os.name``" -msgstr "``name``" - -#: ../source/specifications/dependency-specifiers.rst:236 -#, fuzzy -msgid "``posix``, ``java``" -msgstr "``pipenv``, ``nose``" - -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:73 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:76 +msgid "" +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -#, fuzzy -msgid "``platform_version``" -msgstr "``version``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -#, fuzzy -msgid "``platform.version()``" -msgstr "``version``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:123 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "``version``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -#, fuzzy -msgid "``3.4``, ``2.7``" -msgstr "``0.1.6``, ``1.4.2``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "``requires-python``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -#, fuzzy -msgid "``3.4.0``, ``3.5.0b1``" -msgstr "``2.7.12``, ``3.6.4``" - -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:266 -#, fuzzy -msgid "``cpython``" -msgstr "python" - -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:145 msgid "" -"An error except when defined by the context interpreting the specification." +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 -msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 -msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/direct-url.rst:8 -msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/direct-url.rst:36 -msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:11 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:62 -#, fuzzy -msgid "``pip install app``" -msgstr "Uzi ``pip`` por instali Pipenv:" - -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:32 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:42 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:51 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:64 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/entry-points.rst:68 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/entry-points.rst:73 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 -msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/entry-points.rst:82 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/entry-points.rst:98 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/entry-points.rst:101 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/entry-points.rst:105 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/entry-points.rst:145 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/entry-points.rst:153 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/entry-points.rst:158 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +#| msgid "distlib" +msgid "distro" +msgstr "distlib" + +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "packaging" +msgid "package" +msgstr "pakado" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "To install a specific version:" +msgid "Python-specific package manager" +msgstr "Por instali specifan version:" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:206 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:230 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:262 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:266 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:279 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Krei Virtualajn Mediojn" + +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Tipoj de dokumentaro" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "Uzi ``pip`` por instali Pipenv:" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:143 -msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +msgid "``pip install --prefix=/some/path``" +msgstr "Uzi ``pip`` por instali Pipenv:" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:151 -msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "Uzi ``pip`` por instali Pipenv:" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 -msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 +#: ../source/specifications/inline-script-metadata.rst:3 #, fuzzy -#| msgid "distlib" -msgid "distro" -msgstr "distlib" +#| msgid "Configuring metadata" +msgid "Inline script metadata" +msgstr "Agordi metadatenojn" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "pakado" - -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "To install a specific version:" -msgid "Python-specific package manager" -msgstr "Por instali specifan version:" - -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +#| msgid "pyproject.toml" +msgid "pyproject type" +msgstr "pyproject.toml" + +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/inline-script-metadata.rst:108 +#, fuzzy +msgid "Example" +msgstr "Ekzemploj" + +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Tipoj de dokumentaro" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +#| msgid "Creating pyproject.toml" +msgid "Recommendations" +msgstr "Krei la dosieron pyproject.toml" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:5 +#, fuzzy +msgid "Package name normalization" +msgstr "Versio de pako" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -msgid "Guide users towards virtual environments" -msgstr "Krei Virtualajn Mediojn" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:25 +#, fuzzy +msgid "python tag" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Tipoj de dokumentaro" +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 -msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 +#: ../source/specifications/platform-compatibility-tags.rst:49 #, fuzzy -msgid "``pip install``" -msgstr "Uzi ``pip`` por instali Pipenv:" +msgid "Python Tag" +msgstr "python" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:55 #, fuzzy -msgid "``pip install --prefix=/some/path``" -msgstr "Uzi ``pip`` por instali Pipenv:" +msgid "cp: CPython" +msgstr "python" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:56 +#, fuzzy +msgid "ip: IronPython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 +#: ../source/specifications/platform-compatibility-tags.rst:58 #, fuzzy -msgid "``pip install --user``" -msgstr "Uzi ``pip`` por instali Pipenv:" +msgid "jy: Jython" +msgstr "python" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:107 #, fuzzy -#| msgid "Configuring metadata" -msgid "Inline script metadata" -msgstr "Agordi metadatenojn" +msgid "``manylinux``" +msgstr "Prizorganto" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:132 +msgid "" +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:137 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 -msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -#, fuzzy -msgid "Example" -msgstr "Ekzemploj" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Tipoj de dokumentaro" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Creating pyproject.toml" -msgid "Recommendations" -msgstr "Krei la dosieron pyproject.toml" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -#, fuzzy -msgid "Package name normalization" -msgstr "Versio de pako" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:261 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:264 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -#, fuzzy -msgid "python tag" -msgstr "python" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:300 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -#, fuzzy -msgid "Python Tag" -msgstr "python" - -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -#, fuzzy -msgid "cp: CPython" -msgstr "python" - -#: ../source/specifications/platform-compatibility-tags.rst:56 -#, fuzzy -msgid "ip: IronPython" -msgstr "python" - -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -#, fuzzy -msgid "jy: Jython" -msgstr "python" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:96 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 +#: ../source/specifications/pyproject-toml.rst:6 #, fuzzy -msgid "``manylinux``" -msgstr "Prizorganto" +#| msgid "pyproject.toml" +msgid "``pyproject.toml`` specification" +msgstr "pyproject.toml" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 -msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 -msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" +msgstr "``dynamic``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:138 +#, fuzzy +msgid "``gui-scripts``" +msgstr "``description``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "Prizorganto" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:143 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" +msgstr "Tipo de TOML_: signoĉeno" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 -msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." -msgstr "" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." +msgstr "La nomo de la projekto." -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." +msgstr "La resuma priskribo de la projekto." -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" +msgstr "Tipo de TOML_: signoĉeno aŭ tabelo" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" +msgstr "Tipo de TOML_: tabelo" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." +msgstr "La ŝlosilvortoj pri la projekto." -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 -msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:336 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:346 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:359 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15673,7 +15566,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15682,11 +15575,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15697,21 +15590,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15723,7 +15616,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15734,7 +15627,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15746,41 +15639,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15788,7 +15681,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15796,58 +15689,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15855,7 +15748,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15863,13 +15756,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15878,7 +15771,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15887,18 +15780,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15906,7 +15799,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15916,11 +15809,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15928,15 +15821,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15944,11 +15837,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15956,29 +15849,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15987,11 +15880,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15999,14 +15892,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -16015,7 +15908,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16151,10 +16044,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16326,24 +16219,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Specifiloj" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16351,7 +16244,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16359,19 +16252,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16379,25 +16272,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Versio" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16405,28 +16298,28 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy #| msgid "Version Specifier" msgid "Public version identifiers" msgstr "Versio-Specifilo" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16434,7 +16327,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16442,63 +16335,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16506,11 +16399,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16519,7 +16412,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16529,7 +16422,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16538,7 +16431,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16546,23 +16439,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16576,7 +16469,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16584,7 +16477,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16596,36 +16489,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16633,21 +16526,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16655,35 +16552,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16691,48 +16588,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16740,7 +16637,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16748,11 +16645,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16760,11 +16657,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16772,20 +16669,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16794,13 +16691,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16810,29 +16707,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Versio" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16843,14 +16740,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16858,23 +16755,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Versio de pako" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16883,11 +16780,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16897,11 +16794,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16911,11 +16808,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16923,11 +16820,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16938,11 +16835,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16950,11 +16847,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16962,11 +16859,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16976,11 +16873,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16988,11 +16885,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -17000,11 +16897,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -17012,11 +16909,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -17025,11 +16922,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -17038,11 +16935,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -17052,7 +16949,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -17060,69 +16957,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17130,48 +17027,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17182,7 +17079,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17192,17 +17089,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17211,18 +17108,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17233,7 +17130,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17241,30 +17138,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17272,30 +17169,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17303,60 +17200,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17365,81 +17262,81 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy #| msgid "Version" msgid "Version matching" msgstr "Versio" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17448,7 +17345,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17456,31 +17353,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17488,7 +17385,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17497,7 +17394,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17507,14 +17404,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17523,30 +17420,30 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy #| msgid "Version Specifier" msgid "Version exclusion" msgstr "Versio-Specifilo" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17555,27 +17452,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17585,7 +17482,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17595,13 +17492,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17820,7 +17717,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17828,7 +17725,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17839,16 +17736,16 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy msgid "Remote URL examples::" msgstr "Ekzemploj" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17856,7 +17753,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17864,7 +17761,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17876,43 +17773,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17921,20 +17818,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19243,29 +19140,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." -msgstr "Vidu :pep:`517` kaj :pep:`518` por fonaj informoj kaj detaloj." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "Legu pri :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Spanish \n" @@ -23,7 +23,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n != 1;\n" -"X-Generator: Weblate 5.2\n" +"X-Generator: Weblate 5.3-dev\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -548,6 +548,7 @@ msgid "Deploying Python applications" msgstr "" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -566,6 +567,7 @@ msgid "Incomplete" msgstr "Incompleta" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -669,7 +671,7 @@ msgid "Unix (including Linux and macOS)" msgstr "" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "" @@ -688,6 +690,145 @@ msgstr "" msgid "Configuration management" msgstr "" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution package vs. import package" +msgstr "Paquete de Distribución" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +#, fuzzy +#| msgid "Distribution Package" +msgid "What's a distribution package?" +msgstr "Paquete de Distribución" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -961,7 +1102,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1105,204 +1246,215 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 #, fuzzy -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "Sírvase de ``pip`` para instalar Sphinx:" #: ../source/discussions/setup-py-deprecated.rst:105 #, fuzzy -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy msgid "``python setup.py --version``" msgstr "Versión de Python" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 #, fuzzy msgid "``build``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy msgid "``easy_install``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 #, fuzzy msgid "``install``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 #, fuzzy msgid "``install_data``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 #, fuzzy msgid "``install_egg_info``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy msgid "``install_headers``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 #, fuzzy msgid "``install_lib``" msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/discussions/setup-py-deprecated.rst:146 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" -msgstr "Sírvase de ``pip`` para instalar Sphinx:" +msgstr "``install_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" -msgstr "" +msgstr "``rotate``" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" -msgstr "" +msgstr "``saveopts``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" -msgstr "" +msgstr "``setopt``" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" -msgstr "" +msgstr "``upload_docs``" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" -msgstr "" +msgstr "¿Qué pasa con los comandos personalizados?" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " "any other similar tool. Some examples of such tools are: chuy, make, nox or " "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" +"Del mismo modo, los comandos personalizados :file:`setup.py` están " +"obsoletos. La recomendación es migrar esos comandos personalizados a una " +"herramienta de ejecución de tareas o cualquier otra herramienta similar. " +"Algunos ejemplos de estas herramientas son: chuy, make, nox o tox, pydoit, " +"pyinvoke, taskipy, y thx." -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" -msgstr "" +msgstr "¿Qué pasa con los pasos de construcción personalizados?" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1310,26 +1462,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1646,24 +1798,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1672,22 +1828,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1695,7 +1851,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1704,43 +1860,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1831,14 +1987,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1846,11 +2003,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1859,11 +2016,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1872,67 +2029,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Módulo" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "Índice de paquetes" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "Índice por proyecto" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Proyecto" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1941,7 +2099,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1949,7 +2107,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1957,21 +2115,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1981,48 +2139,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2030,11 +2188,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2043,17 +2201,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2069,12 +2225,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2237,7 +2393,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2306,14 +2462,14 @@ msgid "Column" msgstr "Columna" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Descripción" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Ejemplos" @@ -2671,8 +2827,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2847,6 +3002,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2855,14 +3018,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2870,36 +3033,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2920,14 +3083,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2967,11 +3130,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2979,7 +3142,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2987,16 +3150,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3006,256 +3169,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "Brinde una descripción breve y una larga del proyecto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "Proporcione un URL de página principal del proyecto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "Añada palabras clave que describan su proyecto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3265,78 +3240,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3345,24 +3281,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3371,7 +3307,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3383,13 +3319,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3397,12 +3333,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3410,56 +3346,15 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 -msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" "Different Python projects may use different versioning schemes based on the " "needs of that particular project, but all of them are required to comply " @@ -3468,11 +3363,11 @@ msgid "" "libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3480,42 +3375,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3523,58 +3418,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3582,44 +3477,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3629,17 +3524,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3648,13 +3543,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3664,7 +3559,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3672,21 +3567,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3695,22 +3590,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3718,23 +3613,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3743,11 +3638,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3755,95 +3650,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3851,7 +3746,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3859,7 +3754,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3868,7 +3763,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3878,78 +3773,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Crear cuenta" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3957,7 +3852,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3965,14 +3860,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4086,96 +3973,89 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "" +#, fuzzy +#| msgid "Examples" +msgid "Examples:" +msgstr "Ejemplos" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4190,9 +4070,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4474,7 +4354,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4579,6 +4459,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "Por ejemplo:" @@ -4607,7 +4488,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4787,7 +4668,7 @@ msgid "Create and activate a virtual environment" msgstr "Facultativamente, cree un entorno virtual" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4851,35 +4732,35 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 #, fuzzy #| msgid "Optionally, create a virtual environment" msgid "Activate a virtual environment" msgstr "Facultativamente, cree un entorno virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4887,160 +4768,160 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 #, fuzzy #| msgid "Optionally, create a virtual environment" msgid "Deactivate a virtual environment" msgstr "Facultativamente, cree un entorno virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 #, fuzzy #| msgid "Optionally, create a virtual environment" msgid "Reactivate a virtual environment" msgstr "Facultativamente, cree un entorno virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "Instalación de paquetes" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "Instalación de paquetes" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "To install a specific version:" msgid "Install a specific package version" msgstr "Para instalar una versión específica:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Installing \"Extras\"" msgid "Install extras" msgstr "Instalando \"Extras\"" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing packages for your project" msgid "Install a package from source" msgstr "Instalación de paquetes para su proyecto" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5048,114 +4929,114 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 #, fuzzy #| msgid "Installing from other sources" msgid "Install from version control systems" msgstr "Instalación a partir de otras fuentes" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 #, fuzzy #| msgid "Installing from other sources" msgid "Install from local archives" msgstr "Instalación a partir de otras fuentes" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing from other Indexes" msgid "Install from other package indexes" msgstr "Instalación a partir de otros índices" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy #| msgid "Requirements files" msgid "Using a requirements file" msgstr "Archivos de requisitos" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5609,14 +5490,12 @@ msgstr "Paquete de Distribución" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -#, fuzzy -msgid ":ref:`declaring-build-dependencies`" -msgstr "Dependencias externas" +msgid ":ref:`pyproject-build-system-table`" +msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5688,7 +5567,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5727,11 +5606,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "Nombre de proyecto" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6348,11 +6229,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6361,19 +6242,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6384,17 +6265,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6402,17 +6283,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6420,7 +6301,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6428,7 +6309,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6437,27 +6318,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6465,13 +6346,13 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 #, fuzzy #| msgid "Using installed packages" msgid "Legacy namespace packages" msgstr "Utilización de paquetes instalados" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6479,13 +6360,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6493,11 +6374,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6506,21 +6387,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6528,17 +6409,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6550,19 +6431,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6571,13 +6452,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6875,44 +6756,52 @@ msgstr "Formato de instalación" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6920,39 +6809,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6961,52 +6850,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7759,8 +7648,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7879,95 +7768,132 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 #, fuzzy #| msgid "List keywords that describe your project." msgid "Put the version of your project." msgstr "Añada palabras clave que describan su proyecto." -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy #| msgid "Requirements files" msgid "Dependencies and requirements" msgstr "Archivos de requisitos" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 #, fuzzy #| msgid "Creating the package files" msgid "Creating executable scripts" msgstr "Creación de los archivos del paquete" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7975,131 +7901,182 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 #, fuzzy #| msgid "For example:" msgid "A full example" msgstr "Por ejemplo:" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8536,8 +8513,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8548,9 +8525,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8609,13 +8585,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8628,18 +8603,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8648,18 +8623,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8670,42 +8645,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8714,22 +8689,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8737,15 +8712,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8754,14 +8729,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8774,17 +8749,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8792,17 +8767,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8814,17 +8789,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8835,34 +8810,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8870,46 +8845,46 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy #| msgid "`pip-tools `_" msgid "`GitHub `__" msgstr "`pip-tools `_" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8918,18 +8893,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8940,17 +8915,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8958,17 +8933,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8978,17 +8953,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8998,17 +8973,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9018,18 +8993,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9040,18 +9015,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9079,7 +9054,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9098,24 +9073,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9123,21 +9098,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9145,17 +9120,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10529,25 +10504,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10558,86 +10525,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10646,35 +10580,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10682,32 +10616,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10715,41 +10649,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10758,14 +10692,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10773,7 +10707,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10781,33 +10715,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10815,25 +10749,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10844,63 +10778,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10908,71 +10842,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10980,28 +10914,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11010,22 +10944,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11033,29 +10967,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11065,7 +10999,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11073,25 +11007,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11099,85 +11033,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11187,11 +11075,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11200,38 +11088,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11239,7 +11127,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11247,18 +11135,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11267,7 +11155,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11278,7 +11166,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11296,7 +11184,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11305,70 +11193,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "Nombre" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11470,41 +11355,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "Versión" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11512,20 +11397,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11533,27 +11418,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11561,19 +11458,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11581,7 +11478,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11589,7 +11486,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11597,31 +11494,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11735,91 +11632,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Responsable" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11829,11 +11726,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11841,43 +11738,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11885,64 +11782,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11950,13 +11847,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11964,36 +11861,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12002,13 +11899,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12016,20 +11913,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12037,7 +11934,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12047,11 +11944,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12059,7 +11956,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12069,18 +11966,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12089,7 +11986,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12100,65 +11997,65 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 #, fuzzy #| msgid "Requirements File" msgid "Requires" msgstr "Archivo de requisitos" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12169,33 +12066,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12204,3382 +12101,3377 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Especificación" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Especificación" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -#, fuzzy -msgid "``dependencies``" -msgstr "Dependencias externas" - -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "Responsable" - -#: ../source/specifications/declaring-project-metadata.rst:64 +#: ../source/specifications/dependency-specifiers.rst:132 #, fuzzy -msgid "``optional-dependencies``" -msgstr "Dependencias externas" - -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "" +msgid "Names" +msgstr "Nombre" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Versión" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:183 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:219 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 -msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url.rst:8 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:17 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:24 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:29 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 +#: ../source/specifications/direct-url.rst:36 msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -#, fuzzy -msgid "Names" -msgstr "Nombre" - -#: ../source/specifications/dependency-specifiers.rst:132 -msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url.rst:54 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 -msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 -msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 +#: ../source/specifications/direct-url.rst:62 #, fuzzy -msgid "Versions" -msgstr "Versión" +msgid "``pip install app``" +msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:68 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 -msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Versión de Python" +#: ../source/specifications/direct-url-data-structure.rst:58 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:70 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:73 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:76 +msgid "" +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "Versión de Python" - -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "Versión de Python" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 -msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url.rst:8 -msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/direct-url.rst:24 -msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:7 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:11 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:32 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" -msgstr "" - -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:51 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:62 -#, fuzzy -msgid "``pip install app``" -msgstr "Sírvase de ``pip`` para instalar Sphinx:" - -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" -msgstr "" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Formato de archivo" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:82 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:98 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:101 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:105 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 -msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/entry-points.rst:130 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/entry-points.rst:138 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/entry-points.rst:145 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/entry-points.rst:153 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/entry-points.rst:158 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:6 +#, fuzzy +msgid "Externally Managed Environments" +msgstr "Entorno virtual" + +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 -msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "packaging" +msgid "package" +msgstr "empaquetado" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "To install a specific version:" +msgid "Python-specific package manager" +msgstr "Para instalar una versión específica:" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +#| msgid "PyPA specifications" +msgid "This specification is twofold." +msgstr "Especificaciones de PyPA" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:255 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 -msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:279 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Facultativamente, cree un entorno virtual" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/entry-points.rst:14 -msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" -msgstr "Formato de archivo" +#: ../source/specifications/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Tipos de documentación" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "Sírvase de ``pip`` para instalar Sphinx:" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "Por ejemplo::" +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +msgid "``pip install --prefix=/some/path``" +msgstr "Sírvase de ``pip`` para instalar Sphinx:" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:128 -msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "Sírvase de ``pip`` para instalar Sphinx:" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -#, fuzzy -msgid "Externally Managed Environments" -msgstr "Entorno virtual" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 -msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Especificaciones de PyPA" + +#: ../source/specifications/index.rst:6 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:3 +#, fuzzy +#| msgid "Configuring metadata" +msgid "Inline script metadata" +msgstr "Configuración de los metadatos" + +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "empaquetado" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 +#: ../source/specifications/inline-script-metadata.rst:79 #, fuzzy -#| msgid "To install a specific version:" -msgid "Python-specific package manager" -msgstr "Para instalar una versión específica:" +#| msgid "Project name" +msgid "pyproject type" +msgstr "Nombre de proyecto" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:94 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:108 +#, fuzzy +msgid "Example" +msgstr "Ejemplos" + +#: ../source/specifications/inline-script-metadata.rst:110 +msgid "" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 +#: ../source/specifications/inline-script-metadata.rst:149 #, fuzzy -#| msgid "PyPA specifications" -msgid "This specification is twofold." -msgstr "Especificaciones de PyPA" +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Tipos de documentación" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:208 +msgid "" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:212 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +#| msgid "Tool recommendations" +msgid "Recommendations" +msgstr "Recomendaciones de herramientas" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:5 +#, fuzzy +msgid "Package name normalization" +msgstr "Versión del paquete" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "Traducciones" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Etiquetas de compatibilidad con plataformas" + +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -msgid "Guide users towards virtual environments" -msgstr "Facultativamente, cree un entorno virtual" +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Tipos de documentación" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -msgid "``pip install``" -msgstr "Sírvase de ``pip`` para instalar Sphinx:" - -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -#, fuzzy -msgid "``pip install --prefix=/some/path``" -msgstr "Sírvase de ``pip`` para instalar Sphinx:" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -msgid "``pip install --user``" -msgstr "Sírvase de ``pip`` para instalar Sphinx:" +#: ../source/specifications/platform-compatibility-tags.rst:79 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 -msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" -msgstr "Especificaciones de PyPA" +#: ../source/specifications/platform-compatibility-tags.rst:107 +#, fuzzy +msgid "``manylinux``" +msgstr "Responsable" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -#, fuzzy -#| msgid "Configuring metadata" -msgid "Inline script metadata" -msgstr "Configuración de los metadatos" +#: ../source/specifications/platform-compatibility-tags.rst:114 +msgid "" +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 -msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" +msgstr "Herramienta" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "Project name" -msgid "pyproject type" -msgstr "Nombre de proyecto" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -#, fuzzy -msgid "Example" -msgstr "Ejemplos" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Tipos de documentación" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Tool recommendations" -msgid "Recommendations" -msgstr "Recomendaciones de herramientas" - -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -#, fuzzy -msgid "Package name normalization" -msgstr "Versión del paquete" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "Traducciones" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" -msgstr "Etiquetas de compatibilidad con plataformas" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:289 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "El archivo :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" +"El formato (definido originalmente por el paquete :ref:`distutils`) es:" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." -msgstr "" +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" +msgstr "Configuraciones habituales" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." -msgstr "" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" +msgstr "Uso de una ficha de PyPI" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" +msgstr "Uso de otro índice de paquetes" + +#: ../source/specifications/pypirc.rst:104 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -#, fuzzy -msgid "``manylinux``" -msgstr "Responsable" - -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 -msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "Herramienta" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:134 +#, fuzzy +msgid "``dependencies``" +msgstr "Dependencias externas" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "Responsable" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:143 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "Dependencias externas" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:254 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:260 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:265 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:275 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:285 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 -msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 -msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 -msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:336 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" -msgstr "El archivo :file:`.pypirc`" - -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -"El formato (definido originalmente por el paquete :ref:`distutils`) es:" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:365 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:390 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" -msgstr "Configuraciones habituales" - -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" -msgstr "Uso de una ficha de PyPI" - -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" -msgstr "Uso de otro índice de paquetes" +#: ../source/specifications/pyproject-toml.rst:427 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15587,7 +15479,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15596,11 +15488,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15611,21 +15503,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15637,7 +15529,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15648,7 +15540,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15660,7 +15552,7 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 #, fuzzy msgid "" "This ``.dist-info`` directory may contain the following files, described in " @@ -15669,37 +15561,37 @@ msgstr "" "El directorio ``.dist-info`` puede contener los archivos que se describen a " "detalle a continuación:" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "``METADATA``: contiene metadatos sobre el proyecto" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "``RECORD``: registra la lista de archivos instalados." -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" "``INSTALLER``: registra el nombre de la herramienta utilizada para instalar " "el proyecto." -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15707,7 +15599,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15715,58 +15607,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "El archivo METADATA" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "El archivo RECORD" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "delimitador de campos: ``,`` (coma)," -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15774,7 +15666,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15782,13 +15674,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15797,7 +15689,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15806,18 +15698,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15825,7 +15717,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15834,12 +15726,19 @@ msgid "" "``RECORD`` must be updated, otherwise uninstalling the package will leave " "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" +"Está *fuertemente desaconsejado* que un paquete instalado se modifique a sí " +"mismo (por ejemplo, almacenar archivos de caché bajo su espacio de nombres " +"en ``site-packages``). Los cambios dentro de ``site-packages`` deben dejarse " +"a herramientas de instalación especializadas como pip. Si un paquete es " +"modificado de esta manera, entonces el ``RECORD`` debe ser actualizado, de " +"lo contrario la desinstalación del paquete dejará archivos no listados en su " +"lugar (posiblemente resultando en un paquete de espacio de nombres zombie)." -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "El archivo INSTALLER" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15847,15 +15746,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15863,11 +15762,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15875,29 +15774,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15906,11 +15805,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15918,14 +15817,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15934,7 +15833,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16069,10 +15968,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16244,24 +16143,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Especificaciones" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16269,7 +16168,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16277,19 +16176,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16297,25 +16196,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Versión" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16323,26 +16222,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16350,7 +16249,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16358,63 +16257,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16422,11 +16321,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16435,7 +16334,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16445,7 +16344,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16454,7 +16353,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16462,23 +16361,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16492,7 +16391,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16500,7 +16399,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16512,36 +16411,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16549,21 +16448,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "Por ejemplo::" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16571,35 +16474,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16607,48 +16510,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16656,7 +16559,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16664,11 +16567,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16676,11 +16579,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16688,20 +16591,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16710,13 +16613,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16726,29 +16629,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Versión" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16759,14 +16662,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16774,23 +16677,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Traducciones" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16799,11 +16702,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16813,11 +16716,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16827,11 +16730,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16839,11 +16742,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16854,11 +16757,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16866,11 +16769,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16878,11 +16781,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16892,11 +16795,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16904,11 +16807,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16916,11 +16819,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16928,11 +16831,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16941,11 +16844,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16954,11 +16857,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16968,7 +16871,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16976,69 +16879,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17046,48 +16949,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17098,7 +17001,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17108,17 +17011,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17127,18 +17030,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17149,7 +17052,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17157,30 +17060,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17188,30 +17091,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17219,60 +17122,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17281,81 +17184,81 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy #| msgid "Version" msgid "Version matching" msgstr "Versión" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17364,7 +17267,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17372,31 +17275,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17404,7 +17307,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17413,7 +17316,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17423,14 +17326,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17439,29 +17342,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "Versión" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17470,27 +17373,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17500,7 +17403,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17510,13 +17413,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17735,7 +17638,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17743,7 +17646,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17754,17 +17657,17 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy #| msgid "For example::" msgid "Remote URL examples::" msgstr "Por ejemplo::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17772,7 +17675,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17780,7 +17683,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17792,43 +17695,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17837,20 +17740,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19159,28 +19062,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Persian `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -896,7 +1033,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1033,145 +1170,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1179,46 +1323,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1226,26 +1370,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1562,24 +1706,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1588,22 +1736,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1611,7 +1759,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1620,43 +1768,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1747,14 +1895,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1762,11 +1911,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1775,11 +1924,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1788,67 +1937,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1857,7 +2007,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1865,7 +2015,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1873,21 +2023,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "ماژول خالص" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1897,48 +2047,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1946,11 +2096,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1959,17 +2109,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1985,12 +2133,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2149,7 +2297,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2218,14 +2366,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2581,8 +2729,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2757,6 +2904,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2765,14 +2920,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2780,36 +2935,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2830,14 +2985,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2877,11 +3032,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2889,7 +3044,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2897,16 +3052,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2916,256 +3071,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3175,78 +3142,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3255,24 +3183,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3281,7 +3209,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3293,13 +3221,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3307,12 +3235,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3320,69 +3248,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3390,42 +3277,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3433,58 +3320,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3492,44 +3379,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3539,17 +3426,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3558,13 +3445,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3574,7 +3461,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3582,21 +3469,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3605,22 +3492,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3628,23 +3515,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3653,11 +3540,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3665,95 +3552,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3761,7 +3648,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3769,7 +3656,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3778,7 +3665,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3788,78 +3675,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3867,7 +3754,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3875,14 +3762,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3996,96 +3875,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4100,9 +3970,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4384,7 +4254,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4489,6 +4359,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4517,7 +4388,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4693,7 +4564,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4752,33 +4623,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4786,148 +4657,148 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Translations" msgid "Install extras" msgstr "ترجمه‌ها" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4935,106 +4806,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5483,13 +5354,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5559,7 +5429,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5598,11 +5468,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6219,11 +6089,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6232,19 +6102,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6255,17 +6125,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6273,17 +6143,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6291,7 +6161,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6299,7 +6169,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6308,27 +6178,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6336,11 +6206,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6348,13 +6218,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6362,11 +6232,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6375,21 +6245,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6397,17 +6267,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6419,19 +6289,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6440,13 +6310,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6742,44 +6612,52 @@ msgstr "ترجمه‌ها" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6787,39 +6665,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6828,52 +6706,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7626,8 +7504,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7744,89 +7622,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7834,129 +7749,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8391,8 +8357,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8403,9 +8369,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8464,13 +8429,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8483,18 +8447,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8503,18 +8467,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8525,42 +8489,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8569,22 +8533,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8592,15 +8556,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8609,14 +8573,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8629,17 +8593,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8647,17 +8611,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8669,17 +8633,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8690,34 +8654,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8725,44 +8689,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8771,18 +8735,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8793,17 +8757,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8811,17 +8775,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8831,17 +8795,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8851,17 +8815,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8871,18 +8835,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8893,18 +8857,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8932,7 +8896,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8951,24 +8915,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8976,21 +8940,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8998,17 +8962,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10381,25 +10345,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10410,86 +10366,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10498,35 +10421,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10534,32 +10457,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10567,41 +10490,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10610,14 +10533,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10625,7 +10548,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10633,33 +10556,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10667,25 +10590,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10696,63 +10619,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10760,71 +10683,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10832,28 +10755,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10862,22 +10785,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10885,29 +10808,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10917,7 +10840,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10925,25 +10848,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10951,99 +10874,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11052,38 +10929,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11091,7 +10968,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11099,18 +10976,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11119,7 +10996,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11130,7 +11007,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11148,7 +11025,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11157,70 +11034,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11322,41 +11196,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11364,20 +11238,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11385,27 +11259,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11413,19 +11299,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11433,7 +11319,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11441,7 +11327,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11449,31 +11335,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11587,91 +11473,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11681,11 +11567,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11693,43 +11579,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11737,64 +11623,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11802,13 +11688,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11816,36 +11702,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11854,13 +11740,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11868,20 +11754,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11889,7 +11775,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11899,11 +11785,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11911,7 +11797,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11921,18 +11807,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11941,7 +11827,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11952,63 +11838,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12019,33 +11905,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12054,3349 +11940,3344 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "ترجمه‌ها" + +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "ترجمه‌ها" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:189 -msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 -msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:42 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:51 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" -msgstr "" - -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:98 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:145 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:158 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 -msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 -msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 -msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:177 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:206 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 -msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:82 -msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:128 -msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/index.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:151 -msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:56 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:81 +msgid "" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 -msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 -msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:51 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 -msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 -msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:62 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:110 +msgid "" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." -msgstr "" - -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "ترجمه‌ها" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15404,7 +15285,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15413,11 +15294,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15428,21 +15309,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15454,7 +15335,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15465,7 +15346,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15477,41 +15358,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15519,7 +15400,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15527,58 +15408,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15586,7 +15467,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15594,13 +15475,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15609,7 +15490,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15618,18 +15499,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15637,7 +15518,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15647,11 +15528,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15659,15 +15540,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15675,11 +15556,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15687,29 +15568,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15718,11 +15599,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15730,14 +15611,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15746,7 +15627,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15880,10 +15761,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16053,24 +15934,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "مشخصات" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16078,7 +15959,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16086,19 +15967,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16106,25 +15987,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "ترجمه‌ها" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16132,26 +16013,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16159,7 +16040,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16167,63 +16048,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16231,11 +16112,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16244,7 +16125,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16254,7 +16135,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16263,7 +16144,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16271,23 +16152,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16301,7 +16182,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16309,7 +16190,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16321,36 +16202,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16358,21 +16239,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16380,35 +16265,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16416,48 +16301,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16465,7 +16350,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16473,11 +16358,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16485,11 +16370,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16497,20 +16382,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16519,13 +16404,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16535,29 +16420,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "ترجمه‌ها" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16568,14 +16453,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16583,23 +16468,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "ترجمه‌ها" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16608,11 +16493,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16622,11 +16507,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16636,11 +16521,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16648,11 +16533,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16663,11 +16548,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16675,11 +16560,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16687,11 +16572,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16701,11 +16586,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16713,11 +16598,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16725,11 +16610,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16737,11 +16622,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16750,11 +16635,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16763,11 +16648,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16777,7 +16662,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16785,69 +16670,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16855,48 +16740,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16907,7 +16792,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16917,17 +16802,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16936,18 +16821,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16958,7 +16843,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16966,30 +16851,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16997,30 +16882,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17028,60 +16913,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17090,79 +16975,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17171,7 +17056,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17179,31 +17064,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17211,7 +17096,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17220,7 +17105,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17230,14 +17115,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17246,29 +17131,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "ترجمه‌ها" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17277,27 +17162,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17307,7 +17192,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17317,13 +17202,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17542,7 +17427,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17550,7 +17435,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17561,15 +17446,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17577,7 +17462,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17585,7 +17470,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17597,43 +17482,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17642,20 +17527,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18957,28 +18842,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Filipino `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -898,7 +1035,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1035,145 +1172,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1181,46 +1325,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1228,26 +1372,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1564,24 +1708,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1590,22 +1738,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1613,7 +1761,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1622,43 +1770,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1749,14 +1897,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1764,11 +1913,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1777,11 +1926,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1790,67 +1939,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1859,7 +2009,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1867,7 +2017,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1875,21 +2025,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1899,48 +2049,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1948,11 +2098,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1961,17 +2111,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1987,12 +2135,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2151,7 +2299,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2220,14 +2368,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2583,8 +2731,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2759,6 +2906,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2767,14 +2922,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2782,36 +2937,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2832,14 +2987,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2879,11 +3034,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2891,7 +3046,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2899,16 +3054,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2918,256 +3073,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3177,78 +3144,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3257,24 +3185,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3283,7 +3211,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3295,13 +3223,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3309,12 +3237,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3322,69 +3250,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3392,42 +3279,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3435,58 +3322,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3494,44 +3381,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3541,17 +3428,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3560,13 +3447,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3576,7 +3463,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3584,21 +3471,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3607,22 +3494,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3630,23 +3517,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3655,11 +3542,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3667,95 +3554,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3763,7 +3650,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3771,7 +3658,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3780,7 +3667,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3790,78 +3677,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3869,7 +3756,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3877,14 +3764,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3998,96 +3877,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4102,9 +3972,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4386,7 +4256,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4491,6 +4361,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4519,7 +4390,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4695,7 +4566,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4754,33 +4625,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4788,146 +4659,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4935,106 +4806,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5483,13 +5354,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5559,7 +5429,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5598,11 +5468,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6219,11 +6089,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6232,19 +6102,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6255,17 +6125,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6273,17 +6143,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6291,7 +6161,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6299,7 +6169,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6308,27 +6178,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6336,11 +6206,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6348,13 +6218,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6362,11 +6232,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6375,21 +6245,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6397,17 +6267,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6419,19 +6289,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6440,13 +6310,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6740,44 +6610,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6785,39 +6663,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6826,52 +6704,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7624,8 +7502,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7742,89 +7620,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7832,129 +7747,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8389,8 +8355,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8401,9 +8367,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8462,13 +8427,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8481,18 +8445,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8501,18 +8465,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8523,42 +8487,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8567,22 +8531,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8590,15 +8554,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8607,14 +8571,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8627,17 +8591,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8645,17 +8609,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8667,17 +8631,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8688,34 +8652,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8723,44 +8687,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8769,18 +8733,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8791,17 +8755,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8809,17 +8773,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8829,17 +8793,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8849,17 +8813,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8869,18 +8833,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8891,18 +8855,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8930,7 +8894,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8949,24 +8913,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8974,21 +8938,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8996,17 +8960,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10379,25 +10343,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10408,86 +10364,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10496,35 +10419,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10532,32 +10455,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10565,41 +10488,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10608,14 +10531,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10623,7 +10546,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10631,33 +10554,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10665,25 +10588,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10694,63 +10617,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10758,71 +10681,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10830,28 +10753,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10860,22 +10783,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10883,29 +10806,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10915,7 +10838,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10923,25 +10846,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10949,99 +10872,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11050,38 +10927,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11089,7 +10966,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11097,18 +10974,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11117,7 +10994,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11128,7 +11005,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11146,7 +11023,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11155,70 +11032,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11320,41 +11194,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11362,20 +11236,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11383,27 +11257,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11411,19 +11297,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11431,7 +11317,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11439,7 +11325,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11447,31 +11333,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11585,91 +11471,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11679,11 +11565,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11691,43 +11577,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11735,64 +11621,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11800,13 +11686,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11814,36 +11700,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11852,13 +11738,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11866,20 +11752,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11887,7 +11773,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11897,11 +11783,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11909,7 +11795,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11919,18 +11805,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11939,7 +11825,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11950,63 +11836,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12017,33 +11903,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12052,3347 +11938,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15400,7 +15281,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15409,11 +15290,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15424,21 +15305,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15450,7 +15331,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15461,7 +15342,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15473,41 +15354,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15515,7 +15396,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15523,58 +15404,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15582,7 +15463,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15590,13 +15471,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15605,7 +15486,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15614,18 +15495,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15633,7 +15514,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15643,11 +15524,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15655,15 +15536,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15671,11 +15552,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15683,29 +15564,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15714,11 +15595,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15726,14 +15607,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15742,7 +15623,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15876,10 +15757,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16049,22 +15930,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16072,7 +15953,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16080,19 +15961,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16100,24 +15981,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16125,26 +16006,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16152,7 +16033,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16160,63 +16041,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16224,11 +16105,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16237,7 +16118,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16247,7 +16128,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16256,7 +16137,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16264,23 +16145,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16294,7 +16175,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16302,7 +16183,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16314,36 +16195,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16351,21 +16232,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16373,35 +16258,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16409,48 +16294,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16458,7 +16343,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16466,11 +16351,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16478,11 +16363,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16490,20 +16375,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16512,13 +16397,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16528,28 +16413,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16560,14 +16445,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16575,22 +16460,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16599,11 +16484,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16613,11 +16498,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16627,11 +16512,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16639,11 +16524,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16654,11 +16539,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16666,11 +16551,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16678,11 +16563,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16692,11 +16577,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16704,11 +16589,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16716,11 +16601,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16728,11 +16613,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16741,11 +16626,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16754,11 +16639,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16768,7 +16653,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16776,69 +16661,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16846,48 +16731,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16898,7 +16783,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16908,17 +16793,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16927,18 +16812,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16949,7 +16834,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16957,30 +16842,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16988,30 +16873,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17019,60 +16904,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17081,79 +16966,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17162,7 +17047,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17170,31 +17055,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17202,7 +17087,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17211,7 +17096,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17221,14 +17106,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17237,28 +17122,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17267,27 +17152,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17297,7 +17182,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17307,13 +17192,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17532,7 +17417,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17540,7 +17425,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17551,15 +17436,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17567,7 +17452,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17575,7 +17460,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17587,43 +17472,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17632,20 +17517,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18947,28 +18832,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: French `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -1028,7 +1167,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1177,172 +1316,179 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "Oui (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "Oui (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:105 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy msgid "``python setup.py --version``" msgstr "Version de Python" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``build``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 #, fuzzy #| msgid "``pypinfo``" msgid "``dist_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``easy_install``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 #, fuzzy #| msgid "``pypinfo``" msgid "``egg_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install_data``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install_egg_info``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install_headers``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install_lib``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" msgid "``install_scripts``" msgstr "Oui (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1350,48 +1496,48 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 #, fuzzy #| msgid "pyproject.toml" msgid "Is ``pyproject.toml`` mandatory?" msgstr "pyproject.toml" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1399,26 +1545,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1736,24 +1882,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1762,23 +1912,23 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 #, fuzzy msgid "The built distributions (wheels)" msgstr "Distribution compilée" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1786,7 +1936,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1795,43 +1945,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1922,14 +2072,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Egg" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1937,11 +2088,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "Module d'extension" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1950,11 +2101,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1963,67 +2114,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Module" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Projet" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2032,7 +2184,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2040,7 +2192,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -2048,21 +2200,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Module pur" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2072,11 +2224,11 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "Index des Paquets Python (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " @@ -2086,31 +2238,31 @@ msgstr "" "communauté Python. Il est ouvert à tous les développeurs Python pour qu'ils " "utilisent et distribuent leurs paquets." -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "Version" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." @@ -2118,7 +2270,7 @@ msgstr "" "Une image d'un :term:`Projet` à un certain moment dans le temps, défini par " "un numéro de version." -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2126,11 +2278,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2139,17 +2291,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2165,12 +2315,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2331,7 +2481,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2400,14 +2550,14 @@ msgid "Column" msgstr "Colonne" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Description" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Exemples" @@ -2768,8 +2918,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "Références" @@ -2944,6 +3093,16 @@ msgid "Packaging and distributing projects" msgstr "Paqueter et distribuer des projets" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2017-12-01" +msgid "2023-12-14" +msgstr "2017-12-01" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2952,14 +3111,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2967,36 +3126,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "Installez « twine » [1]_ :" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "Configurer votre projet" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "Fichiers initiaux" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -3017,14 +3176,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rst / README.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -3064,11 +3223,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -3076,7 +3235,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3084,16 +3243,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3103,258 +3262,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "Renseignez une description courte et longue pour votre projet." - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "Renseignez une URL pour la page d'accueil de votre projet." - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "Renseignez des informations sur l'auteur." - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" -"Renseignez une liste de classifieurs qui catégorisent votre projet. Pour la " -"liste complète, consultez https://pypi.org/classifiers/." - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "Listez les mots-clés qui décrivent votre projet." - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "``packages``" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3364,78 +3333,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "Et ainsi de suite." - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3444,24 +3374,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3470,7 +3400,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3482,13 +3412,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3496,12 +3426,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3509,69 +3439,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3579,42 +3468,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3622,58 +3511,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3681,44 +3570,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3728,17 +3617,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3747,13 +3636,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3763,7 +3652,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3771,21 +3660,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3794,22 +3683,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3817,23 +3706,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3842,11 +3731,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3854,95 +3743,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3950,7 +3839,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3958,7 +3847,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3967,7 +3856,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3977,78 +3866,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Créer un compte" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -4056,7 +3945,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -4064,14 +3953,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4185,96 +4066,89 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "" +#, fuzzy +#| msgid "Examples" +msgid "Examples:" +msgstr "Exemples" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4289,9 +4163,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4573,7 +4447,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4678,6 +4552,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 #, fuzzy msgid "For example:" msgstr "Exemples" @@ -4707,7 +4582,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4883,7 +4758,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4946,35 +4821,35 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 #, fuzzy #| msgid "Virtual Environment" msgid "Activate a virtual environment" msgstr "Environnement virtuel" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4982,155 +4857,155 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 #, fuzzy #| msgid "Virtual Environment" msgid "Deactivate a virtual environment" msgstr "Environnement virtuel" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 #, fuzzy #| msgid "Virtual Environment" msgid "Reactivate a virtual environment" msgstr "Environnement virtuel" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Install `pypinfo`_ using pip." msgid "Install packages using pip" msgstr "Installez `pypinfo`_ à l'aide de pip." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Uninstall Packages" msgid "Install a package" msgstr "Désinstaller des paquets" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy msgid "Install extras" msgstr "Format d'installation" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5138,108 +5013,108 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy #| msgid "install_requires vs requirements files" msgid "Using a requirements file" msgstr "Fichiers requirements vs install_requires" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5694,13 +5569,12 @@ msgstr "Paqueter et distribuer des projets" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5776,7 +5650,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5815,11 +5689,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "pyproject.toml" +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6438,11 +6314,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6451,19 +6327,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6474,17 +6350,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6492,17 +6368,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6510,7 +6386,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6518,7 +6394,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6527,27 +6403,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6555,11 +6431,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6567,13 +6443,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6581,11 +6457,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6594,21 +6470,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6616,17 +6492,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6638,19 +6514,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6659,13 +6535,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6963,44 +6839,52 @@ msgstr "Format d'installation" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -7008,39 +6892,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -7049,52 +6933,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7847,8 +7731,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7967,93 +7851,130 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 #, fuzzy #| msgid "Configuring your project" msgid "Put the version of your project." msgstr "Configurer votre projet" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy #| msgid "install_requires vs requirements files" msgid "Dependencies and requirements" msgstr "Fichiers requirements vs install_requires" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -8061,87 +7982,122 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 #, fuzzy #| msgid "Configuring your project" msgid "About your project" msgstr "Configurer votre projet" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 #, fuzzy #| msgid "" #| "Provide a list of classifiers that categorize your project. For a full " @@ -8153,46 +8109,62 @@ msgstr "" "Renseignez une liste de classifieurs qui catégorisent votre projet. Pour la " "liste complète, consultez https://pypi.org/classifiers/." -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 #, fuzzy msgid "A full example" msgstr "Exemples" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8633,8 +8605,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8645,9 +8617,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8706,13 +8677,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8725,18 +8695,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8745,18 +8715,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8767,42 +8737,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8811,22 +8781,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8834,15 +8804,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8851,14 +8821,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8871,17 +8841,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8889,17 +8859,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8911,17 +8881,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8932,35 +8902,35 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 #, fuzzy msgid "meson-python" msgstr "python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8968,44 +8938,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -9014,18 +8984,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -9036,17 +9006,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -9054,17 +9024,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -9074,17 +9044,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -9094,17 +9064,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9114,18 +9084,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9136,18 +9106,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9175,7 +9145,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9194,24 +9164,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9219,21 +9189,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9241,17 +9211,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10624,25 +10594,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10653,86 +10615,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10741,35 +10670,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10777,32 +10706,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10810,41 +10739,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10853,14 +10782,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10868,7 +10797,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10876,33 +10805,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10910,25 +10839,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10939,63 +10868,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -11003,71 +10932,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -11075,28 +11004,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11105,22 +11034,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11128,29 +11057,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11160,7 +11089,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11168,25 +11097,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11194,85 +11123,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11282,11 +11165,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11295,38 +11178,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11334,7 +11217,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11342,18 +11225,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11362,7 +11245,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11373,7 +11256,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11391,7 +11274,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11400,70 +11283,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11565,41 +11445,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11607,20 +11487,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11628,27 +11508,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11656,19 +11548,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11676,7 +11568,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11684,7 +11576,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11692,31 +11584,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11830,91 +11722,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11924,11 +11816,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11936,43 +11828,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11980,64 +11872,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -12045,13 +11937,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -12059,36 +11951,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12097,13 +11989,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12111,20 +12003,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12132,7 +12024,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12142,11 +12034,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12154,7 +12046,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12164,18 +12056,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12184,7 +12076,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12195,63 +12087,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12262,33 +12154,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12297,3376 +12189,3373 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Spécification" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Spécification" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Traductions" + +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Version de Python" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "Version de Python" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "Version de Python" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:268 +#, fuzzy +msgid "``cpython``" +msgstr "python" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "Traductions" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 -msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Version de Python" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "Version de Python" - -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "Version de Python" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -#, fuzzy -msgid "``cpython``" -msgstr "python" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:42 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:51 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" -msgstr "" - -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:98 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:145 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:158 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:6 +#, fuzzy +msgid "Externally Managed Environments" +msgstr "Environnement virtuel" + +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 -msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "``packages``" +msgid "package" +msgstr "``packages``" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 -msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 -msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:182 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:200 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Guide users towards virtual environments" +msgstr "Environnement virtuel" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Types de documentation" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``pip install``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``pip install --user``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/index.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -#, fuzzy -msgid "Externally Managed Environments" -msgstr "Environnement virtuel" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +#| msgid "pyproject.toml" +msgid "pyproject type" +msgstr "pyproject.toml" + +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 -msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "``packages``" -msgid "package" -msgstr "``packages``" - -#: ../source/specifications/externally-managed-environments.rst:64 -msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:98 +msgid "" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:108 +#, fuzzy +msgid "Example" +msgstr "Exemples" + +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Types de documentation" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:208 +msgid "" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 -msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:5 +#, fuzzy +msgid "Package name normalization" +msgstr "Version du paquet" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "Traductions" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 +#: ../source/specifications/platform-compatibility-tags.rst:25 #, fuzzy -#| msgid "Virtual Environment" -msgid "Guide users towards virtual environments" -msgstr "Environnement virtuel" +msgid "python tag" +msgstr "python" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +#, fuzzy +msgid "Use" +msgstr "Usage :" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 +#: ../source/specifications/platform-compatibility-tags.rst:49 +#, fuzzy +msgid "Python Tag" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:55 +#, fuzzy +msgid "cp: CPython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:56 +#, fuzzy +msgid "ip: IronPython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:58 +#, fuzzy +msgid "jy: Jython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Types de documentation" - -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``pip install``" -msgstr "Oui (``python -m pip uninstall``)" +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:95 +msgid "" +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``pip install --user``" -msgstr "Oui (``python -m pip uninstall``)" - -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 -msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 -msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:119 +msgid "" +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:122 +msgid "" +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 -msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 -msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" - -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -#, fuzzy -msgid "Example" -msgstr "Exemples" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Types de documentation" - -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -#, fuzzy -msgid "Package name normalization" -msgstr "Version du paquet" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "Traductions" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -#, fuzzy -msgid "python tag" -msgstr "python" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -#, fuzzy -msgid "Use" -msgstr "Usage :" - -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:303 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -#, fuzzy -msgid "Python Tag" -msgstr "python" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -#, fuzzy -msgid "cp: CPython" -msgstr "python" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -#, fuzzy -msgid "ip: IronPython" -msgstr "python" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -#, fuzzy -msgid "jy: Jython" -msgstr "python" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:61 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/pypirc.rst:65 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:81 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:87 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:96 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``pyproject.toml`` specification" +msgstr "pyproject.toml" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pyproject-toml.rst:14 +msgid "" +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 -msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:346 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:359 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:32 -msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:398 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:411 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:427 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15674,7 +15563,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15683,11 +15572,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15698,21 +15587,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15724,7 +15613,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15735,7 +15624,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15747,41 +15636,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15789,7 +15678,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15797,58 +15686,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15856,7 +15745,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15864,13 +15753,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15879,7 +15768,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15888,18 +15777,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15907,7 +15796,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15917,11 +15806,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15929,15 +15818,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15945,11 +15834,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15957,29 +15846,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15988,11 +15877,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -16000,14 +15889,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -16016,7 +15905,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16152,10 +16041,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16325,24 +16214,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Spécifications" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16350,7 +16239,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16358,19 +16247,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16378,25 +16267,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Traductions" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16404,26 +16293,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16431,7 +16320,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16439,63 +16328,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16503,11 +16392,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16516,7 +16405,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16526,7 +16415,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16535,7 +16424,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16543,23 +16432,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16573,7 +16462,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16581,7 +16470,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16593,36 +16482,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16630,21 +16519,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16652,37 +16545,37 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy #| msgid "Release" msgid "Pre-releases" msgstr "Version" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16690,50 +16583,50 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy #| msgid "Release" msgid "Post-releases" msgstr "Version" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16741,7 +16634,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16749,11 +16642,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16761,11 +16654,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16773,20 +16666,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16795,13 +16688,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16811,29 +16704,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Traductions" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16844,14 +16737,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16859,23 +16752,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Traductions" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16884,11 +16777,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16898,11 +16791,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16912,11 +16805,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16924,11 +16817,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16939,11 +16832,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16951,11 +16844,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16963,11 +16856,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16977,11 +16870,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16989,11 +16882,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -17001,11 +16894,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -17013,11 +16906,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -17026,11 +16919,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -17039,11 +16932,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -17053,7 +16946,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -17061,69 +16954,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17131,48 +17024,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17183,7 +17076,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17193,17 +17086,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17212,18 +17105,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17234,7 +17127,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17242,30 +17135,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17273,30 +17166,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17304,60 +17197,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17366,79 +17259,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17447,7 +17340,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17455,31 +17348,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17487,7 +17380,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17496,7 +17389,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17506,14 +17399,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17522,29 +17415,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "Traductions" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17553,27 +17446,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17583,7 +17476,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17593,13 +17486,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17820,7 +17713,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17828,7 +17721,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17839,16 +17732,16 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy msgid "Remote URL examples::" msgstr "Exemples" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17856,7 +17749,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17864,7 +17757,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17876,43 +17769,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17921,20 +17814,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19238,28 +19131,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Hindi `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -895,7 +1032,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1034,148 +1171,157 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" -msgstr "" +#, fuzzy +msgid "``python -m twine check --strict dist/*``" +msgstr "पाइथॉन संस्करण" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "पाइथॉन संस्करण" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +#, fuzzy +msgid "``python -m twine upload dist/*``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy msgid "``python setup.py --version``" msgstr "पाइथॉन संस्करण" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "पाइथॉन संस्करण" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1183,46 +1329,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1230,26 +1376,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1566,24 +1712,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1592,22 +1742,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1615,7 +1765,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1624,43 +1774,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1751,14 +1901,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1766,11 +1917,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1779,11 +1930,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1792,67 +1943,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1861,7 +2013,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1869,7 +2021,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1877,21 +2029,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1901,48 +2053,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1950,11 +2102,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1963,17 +2115,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1989,12 +2139,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2153,7 +2303,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2222,14 +2372,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2585,8 +2735,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2761,6 +2910,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2769,14 +2926,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2784,36 +2941,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2834,14 +2991,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2881,11 +3038,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2893,7 +3050,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2901,16 +3058,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2920,256 +3077,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3179,78 +3148,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3259,24 +3189,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3285,7 +3215,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3297,13 +3227,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3311,12 +3241,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3324,69 +3254,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3394,42 +3283,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3437,58 +3326,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3496,44 +3385,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3543,17 +3432,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3562,13 +3451,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3578,7 +3467,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3586,21 +3475,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3609,22 +3498,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3632,23 +3521,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3657,11 +3546,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3669,95 +3558,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3765,7 +3654,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3773,7 +3662,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3782,7 +3671,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3792,78 +3681,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "खाता" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3871,7 +3760,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3879,14 +3768,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4000,96 +3881,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4104,9 +3976,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4388,7 +4260,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4493,6 +4365,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4521,7 +4394,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4699,7 +4572,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4758,33 +4631,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4792,156 +4665,156 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "Installing packages" msgid "Install a specific package version" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Installing packages" msgid "Install extras" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing packages" msgid "Install a package from source" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4949,108 +4822,108 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing packages" msgid "Install from other package indexes" msgstr "पैकेज प्रतिष्ठापन" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5501,13 +5374,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5577,7 +5449,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5616,11 +5488,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "परियोजना" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6237,11 +6111,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6250,19 +6124,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6273,17 +6147,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6291,17 +6165,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6309,7 +6183,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6317,7 +6191,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6326,27 +6200,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6354,11 +6228,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6366,13 +6240,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6380,11 +6254,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6393,21 +6267,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6415,17 +6289,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6437,19 +6311,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6458,13 +6332,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6758,44 +6632,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6803,39 +6685,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6844,52 +6726,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7642,8 +7524,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7760,89 +7642,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7850,129 +7769,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8407,8 +8377,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8419,9 +8389,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8480,13 +8449,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8499,18 +8467,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8519,18 +8487,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8541,42 +8509,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8585,22 +8553,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8608,15 +8576,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8625,14 +8593,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8645,17 +8613,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8663,17 +8631,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8685,17 +8653,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8706,34 +8674,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8741,44 +8709,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8787,18 +8755,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8809,17 +8777,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8827,17 +8795,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8847,17 +8815,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8867,17 +8835,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8887,18 +8855,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8909,18 +8877,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8948,7 +8916,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8967,24 +8935,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8992,21 +8960,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9014,17 +8982,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10397,25 +10365,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10426,86 +10386,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10514,35 +10441,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10550,32 +10477,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10583,41 +10510,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10626,14 +10553,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10641,7 +10568,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10649,33 +10576,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10683,25 +10610,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10712,63 +10639,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10776,71 +10703,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10848,28 +10775,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10878,22 +10805,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10901,29 +10828,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10933,7 +10860,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10941,25 +10868,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10967,85 +10894,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11055,11 +10936,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11068,38 +10949,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11107,7 +10988,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11115,18 +10996,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11135,7 +11016,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11146,7 +11027,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11164,7 +11045,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11173,70 +11054,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11338,41 +11216,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11380,20 +11258,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11401,27 +11279,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11429,19 +11319,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11449,7 +11339,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11457,7 +11347,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11465,31 +11355,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11603,91 +11493,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11697,11 +11587,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11709,43 +11599,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11753,64 +11643,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11818,13 +11708,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11832,36 +11722,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11870,13 +11760,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11884,20 +11774,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11905,7 +11795,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11915,11 +11805,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11927,7 +11817,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11937,18 +11827,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11957,7 +11847,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11968,63 +11858,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12035,33 +11925,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12070,3354 +11960,3349 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 -msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 -msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "पाइथॉन संस्करण" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "पाइथॉन संस्करण" - -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "पाइथॉन संस्करण" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:475 -msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:7 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" -msgstr "" - -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:11 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:14 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:24 -msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:29 -msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:32 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." -msgstr "" - -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:68 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:130 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:145 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:153 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:158 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 -msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 -msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 -msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 -msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "पैकेज प्रतिष्ठापन" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 -msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:170 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:182 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 -msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." -msgstr "" - -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." -msgstr "" - -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "" - -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:82 -msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:98 -msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:151 -msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 -msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/index.rst:6 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 -msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 +#: ../source/specifications/inline-script-metadata.rst:79 #, fuzzy -#| msgid "Installing packages" -msgid "Python-specific package manager" -msgstr "पैकेज प्रतिष्ठापन" +#| msgid "Project name" +msgid "pyproject type" +msgstr "परियोजना" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:94 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:130 +msgid "" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:208 +msgid "" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 -msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "Project name" -msgid "pyproject type" -msgstr "परियोजना" - -#: ../source/specifications/inline-script-metadata.rst:81 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:172 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:186 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15425,7 +15310,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15434,11 +15319,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15449,21 +15334,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15475,7 +15360,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15486,7 +15371,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15498,41 +15383,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15540,7 +15425,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15548,58 +15433,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15607,7 +15492,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15615,13 +15500,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15630,7 +15515,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15639,18 +15524,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15658,7 +15543,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15668,11 +15553,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15680,15 +15565,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15696,11 +15581,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15708,29 +15593,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15739,11 +15624,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15751,14 +15636,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15767,7 +15652,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15901,10 +15786,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16074,22 +15959,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16097,7 +15982,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16105,19 +15990,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16125,24 +16010,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16150,26 +16035,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16177,7 +16062,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16185,63 +16070,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16249,11 +16134,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16262,7 +16147,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16272,7 +16157,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16281,7 +16166,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16289,23 +16174,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16319,7 +16204,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16327,7 +16212,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16339,36 +16224,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16376,21 +16261,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16398,35 +16287,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16434,48 +16323,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16483,7 +16372,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16491,11 +16380,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16503,11 +16392,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16515,20 +16404,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16537,13 +16426,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16553,28 +16442,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16585,14 +16474,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16600,22 +16489,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16624,11 +16513,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16638,11 +16527,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16652,11 +16541,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16664,11 +16553,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16679,11 +16568,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16691,11 +16580,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16703,11 +16592,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16717,11 +16606,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16729,11 +16618,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16741,11 +16630,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16753,11 +16642,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16766,11 +16655,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16779,11 +16668,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16793,7 +16682,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16801,69 +16690,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16871,48 +16760,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16923,7 +16812,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16933,17 +16822,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16952,18 +16841,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16974,7 +16863,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16982,30 +16871,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17013,30 +16902,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17044,60 +16933,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17106,79 +16995,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17187,7 +17076,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17195,31 +17084,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17227,7 +17116,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17236,7 +17125,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17246,14 +17135,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17262,28 +17151,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17292,27 +17181,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17322,7 +17211,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17332,13 +17221,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17557,7 +17446,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17565,7 +17454,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17576,15 +17465,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17592,7 +17481,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17600,7 +17489,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17612,43 +17501,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17657,20 +17546,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18972,28 +18861,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Indonesian `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "dan *import* package tersebut:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -924,7 +1063,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1063,145 +1202,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1209,46 +1355,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1256,26 +1402,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1592,24 +1738,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1618,22 +1768,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1641,7 +1791,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1650,43 +1800,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1777,14 +1927,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1792,11 +1943,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1805,11 +1956,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1818,67 +1969,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1887,7 +2039,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1895,7 +2047,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1903,21 +2055,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1927,48 +2079,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1976,11 +2128,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1989,17 +2141,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2015,12 +2165,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2179,7 +2329,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2248,14 +2398,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2611,8 +2761,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2787,6 +2936,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2795,14 +2952,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2810,36 +2967,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2860,14 +3017,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2907,11 +3064,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2919,7 +3076,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2927,16 +3084,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2946,256 +3103,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:175 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 -msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:201 -msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3205,78 +3174,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3285,24 +3215,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3311,7 +3241,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3323,13 +3253,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3337,12 +3267,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3350,69 +3280,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3420,42 +3309,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3463,58 +3352,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3522,44 +3411,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3569,17 +3458,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3588,13 +3477,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3604,7 +3493,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3612,21 +3501,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3635,22 +3524,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3658,23 +3547,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3683,11 +3572,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3695,95 +3584,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3791,7 +3680,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3799,7 +3688,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3808,7 +3697,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3818,78 +3707,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3897,7 +3786,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3905,14 +3794,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4026,96 +3907,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4130,9 +4002,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4414,7 +4286,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4519,6 +4391,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4547,7 +4420,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4723,7 +4596,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4782,33 +4655,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4816,148 +4689,148 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Translations" msgid "Install extras" msgstr "Penerjemahan" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4965,106 +4838,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5513,13 +5386,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5589,7 +5461,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5628,11 +5500,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6249,11 +6121,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6262,19 +6134,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6285,17 +6157,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6303,17 +6175,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6321,7 +6193,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6329,7 +6201,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6338,27 +6210,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6366,11 +6238,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6378,13 +6250,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6392,11 +6264,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6405,21 +6277,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6427,17 +6299,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6449,19 +6321,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6470,13 +6342,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6772,44 +6644,52 @@ msgstr "Penerjemahan" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6817,39 +6697,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6858,52 +6738,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7656,8 +7536,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7774,89 +7654,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7864,129 +7781,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8421,8 +8389,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8433,9 +8401,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8494,13 +8461,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8513,18 +8479,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8533,18 +8499,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8555,42 +8521,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8599,22 +8565,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8622,15 +8588,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8639,14 +8605,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8659,17 +8625,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8677,17 +8643,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8699,17 +8665,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8720,34 +8686,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8755,44 +8721,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8801,18 +8767,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8823,17 +8789,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8841,17 +8807,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8861,17 +8827,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8881,17 +8847,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8901,18 +8867,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8923,18 +8889,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8962,7 +8928,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8981,24 +8947,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9006,21 +8972,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9028,17 +8994,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10411,25 +10377,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10440,86 +10398,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10528,35 +10453,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10564,32 +10489,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10597,41 +10522,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10640,14 +10565,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10655,7 +10580,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10663,33 +10588,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10697,25 +10622,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10726,63 +10651,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10790,71 +10715,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10862,28 +10787,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10892,22 +10817,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10915,29 +10840,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10947,7 +10872,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10955,25 +10880,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10981,99 +10906,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11082,38 +10961,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11121,7 +11000,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11129,18 +11008,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11149,7 +11028,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11160,7 +11039,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11178,7 +11057,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11187,70 +11066,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11352,41 +11228,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11394,20 +11270,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11415,27 +11291,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11443,19 +11331,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11463,7 +11351,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11471,7 +11359,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11479,31 +11367,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11617,91 +11505,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11711,11 +11599,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11723,43 +11611,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11767,64 +11655,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11832,13 +11720,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11846,36 +11734,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11884,13 +11772,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11898,20 +11786,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11919,7 +11807,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11929,11 +11817,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11941,7 +11829,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11951,18 +11839,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11971,7 +11859,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11982,63 +11870,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12049,33 +11937,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12084,3353 +11972,3348 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Spesifikasi" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Spesifikasi" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Penerjemahan" + +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:183 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:8 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:17 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:36 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "Penerjemahan" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:42 +msgid "" +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 -msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 -msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:7 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" -msgstr "" - -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:11 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:14 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:24 -msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:29 -msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:32 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." -msgstr "" - -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:68 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:130 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:145 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:153 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:158 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 -msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:46 -msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 -msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 -msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:173 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 -msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 -msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:143 -msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/index.rst:6 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:156 -msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:6 +msgid "" +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:59 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 -msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:103 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 -msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:130 +msgid "" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 -msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Jenis-jenis dokumentasi" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 -msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:69 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:110 +msgid "" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Jenis-jenis dokumentasi" - -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "Penerjemahan" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15438,7 +15321,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15447,11 +15330,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15462,21 +15345,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15488,7 +15371,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15499,7 +15382,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15511,41 +15394,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15553,7 +15436,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15561,58 +15444,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15620,7 +15503,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15628,13 +15511,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15643,7 +15526,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15652,18 +15535,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15671,7 +15554,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15681,11 +15564,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15693,15 +15576,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15709,11 +15592,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15721,29 +15604,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15752,11 +15635,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15764,14 +15647,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15780,7 +15663,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15914,10 +15797,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16087,24 +15970,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Spesifikasi" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16112,7 +15995,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16120,19 +16003,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16140,25 +16023,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Penerjemahan" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16166,26 +16049,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16193,7 +16076,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16201,63 +16084,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16265,11 +16148,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16278,7 +16161,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16288,7 +16171,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16297,7 +16180,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16305,23 +16188,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16335,7 +16218,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16343,7 +16226,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16355,36 +16238,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16392,21 +16275,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16414,35 +16301,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16450,48 +16337,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16499,7 +16386,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16507,11 +16394,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16519,11 +16406,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16531,20 +16418,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16553,13 +16440,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16569,29 +16456,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Penerjemahan" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16602,14 +16489,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16617,23 +16504,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Penerjemahan" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16642,11 +16529,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16656,11 +16543,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16670,11 +16557,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16682,11 +16569,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16697,11 +16584,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16709,11 +16596,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16721,11 +16608,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16735,11 +16622,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16747,11 +16634,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16759,11 +16646,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16771,11 +16658,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16784,11 +16671,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16797,11 +16684,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16811,7 +16698,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16819,69 +16706,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16889,48 +16776,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16941,7 +16828,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16951,17 +16838,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16970,18 +16857,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16992,7 +16879,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17000,30 +16887,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17031,30 +16918,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17062,60 +16949,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17124,79 +17011,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17205,7 +17092,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17213,31 +17100,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17245,7 +17132,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17254,7 +17141,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17264,14 +17151,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17280,29 +17167,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "Penerjemahan" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17311,27 +17198,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17341,7 +17228,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17351,13 +17238,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17576,7 +17463,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17584,7 +17471,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17595,15 +17482,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17611,7 +17498,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17619,7 +17506,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17631,43 +17518,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17676,20 +17563,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18991,28 +18878,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages , 2021, 2022, 2023. # tsutsu3 , 2023. +# nikkie , 2023. msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" -"PO-Revision-Date: 2023-12-01 22:03+0000\n" -"Last-Translator: moto kawasaki \n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" +"PO-Revision-Date: 2023-12-20 20:17+0000\n" +"Last-Translator: nikkie \n" "Language-Team: Japanese \n" "Language: ja\n" @@ -17,7 +18,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Weblate 5.3-dev\n" +"X-Generator: Weblate 5.3\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -608,6 +609,7 @@ msgid "Deploying Python applications" msgstr "Pythonで書かれたアプリケーションを配置(deploy)する" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -626,6 +628,7 @@ msgid "Incomplete" msgstr "未完了" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -757,7 +760,7 @@ msgid "Unix (including Linux and macOS)" msgstr "Unix (LinuxとmacOSを含む)" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "pex" @@ -783,6 +786,146 @@ msgstr "" msgid "Configuration management" msgstr "設定管理" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "配布パッケージ vs. インポートパッケージ" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"数多くの異なったコンセプトが同じ \"パッケージ\" の名で呼ばれています。この" +"ページでは、\"配布パッケージ\" と \"インポートパッケージ\" という、関連しては" +"いるが全く異なる二つの Python のパッケージングの意味を明らかにします。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "配布パッケージとは何でしょうか？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "そして、パッケージをインポートしましょう:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -1109,12 +1252,15 @@ msgstr "``setup.py`` は非推奨になりましたか？" #: ../source/discussions/setup-py-deprecated.rst:8 msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." msgstr "" +"いいえ、 :term:`setup.py` および :ref:`setuptools` は非推奨にはなっていませ" +"ん。" #: ../source/discussions/setup-py-deprecated.rst:10 #, fuzzy #| msgid "" -#| "No, :term:`setup.py` is not deprecated, it is a valid configuration file " -#| "for :ref:`setuptools` that happens to be written in Python, instead of in " +#| "Setuptools is perfectly usable as a :term:`build backend` for packaging " +#| "Python projects. And :file:`setup.py` is a valid configuration file for :" +#| "ref:`setuptools` that happens to be written in Python, instead of in " #| "*TOML* for example (a similar practice is used by other tools like *nox* " #| "and its :file:`nox.py` configuration file, or *pytest* and :file:" #| "`conftest.py`)." @@ -1123,29 +1269,28 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" -"いいえ、 :term:`setup.py` は非推奨ではありませんし、例えば *TOML* の代わりに" -"たまたま Python で書かれている :ref:`setuptools` 向けの正当な設定ファイルで" -"す (*nox* とその設定ファイルである :file:`nox.py` や *pytest* と :file:" -"`conftest` のような他のツール類でも、よく似たパターンが使われています)。" +"Setuptools は、 Python のプロジェクトをパッケージングすることに完璧に使用可能" +"です。そして、 :file:`setup.py` は、例えば *TOML* の代わりにたまたま Python " +"で書かれている :ref:`setuptools` 向けの正当な設定ファイルです (*nox* とその設" +"定ファイルである :file:`nox.py` や *pytest* と :file:`conftest` のような他の" +"ツール類でも、よく似たパターンが使われています)。" #: ../source/discussions/setup-py-deprecated.rst:18 msgid "" "However, ``python setup.py`` and the use of :file:`setup.py` as a command " "line tool are deprecated." msgstr "" +"しかしながら、 ``python setup.py`` および :file:`setup.py` をコマンドライン" +"ツールとして使うことは非推奨になりました。" #: ../source/discussions/setup-py-deprecated.rst:21 -#, fuzzy -#| msgid "" -#| "This means for example that the following commands **MUST NOT** be run " -#| "anymore:" msgid "" "This means that commands such as the following **MUST NOT** be run anymore:" msgstr "" -"その意味するところは、例えば、次のようなコマンドを実行することはもはや **許さ" -"れない** ということです:" +"その意味するところは、次のようなコマンドを実行することはもはや **許されない" +"** ということです:" #: ../source/discussions/setup-py-deprecated.rst:23 #: ../source/discussions/setup-py-deprecated.rst:35 @@ -1270,209 +1415,184 @@ msgstr "" "非推奨になりました。" #: ../source/discussions/setup-py-deprecated.rst:85 -#, fuzzy -#| msgid "What about custom commands?" msgid "What about other commands?" -msgstr "カスタムコマンドについてはどうでしょうか？" +msgstr "他のコマンドについてはどうでしょうか？" #: ../source/discussions/setup-py-deprecated.rst:87 msgid "What are some replacements for the other ``python setup.py`` commands?" -msgstr "" +msgstr "他の ``python setup.py`` コマンドを置き換えるものは何でしょうか？" #: ../source/discussions/setup-py-deprecated.rst:91 -#, fuzzy -#| msgid "``python setup.py sdist``" msgid "``python setup.py test``" -msgstr "``python setup.py sdist``" +msgstr "``python setup.py test``" #: ../source/discussions/setup-py-deprecated.rst:93 msgid "The recommendation is to use a test runner such as pytest_." -msgstr "" +msgstr "推奨されるものは、pytest_ のようなテストランナーを使うことです。" #: ../source/discussions/setup-py-deprecated.rst:99 msgid "" "``python setup.py check``, ``python setup.py register``, and ``python setup." "py upload``" msgstr "" +"``python setup.py check``, ``python setup.py register``, および ``python " +"setup.py upload``" #: ../source/discussions/setup-py-deprecated.rst:101 msgid "A trusted replacement is :ref:`twine`:" -msgstr "" +msgstr "信頼されている代替物は :ref:`twine` です:" #: ../source/discussions/setup-py-deprecated.rst:103 -#, fuzzy -#| msgid "``python -m build``" -msgid "``python -m twine check``" -msgstr "``python -m build``" +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" #: ../source/discussions/setup-py-deprecated.rst:104 -#, fuzzy -#| msgid "``python -m pip install .``" -msgid "``python -m twine register``" -msgstr "``python -m pip install .``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "``python -m twine register dist/*.whl`` [#not-pypi]_" #: ../source/discussions/setup-py-deprecated.rst:105 -#, fuzzy -#| msgid "``python -m build``" -msgid "``python -m twine upload``" -msgstr "``python -m build``" +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" -#: ../source/discussions/setup-py-deprecated.rst:109 -#, fuzzy -#| msgid "``python setup.py develop``" +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"必ずしもそうではなく、 :term:`PyPI ` でもサポー" +"トされていません。しかし、(例えば :ref:`devpi` のような) 他の :term:`パッケー" +"ジインデックス ` では必要になるかもしれません。" + +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" -msgstr "``python setup.py develop``" +msgstr "``python setup.py --version``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" +"実行可能な代替案は (他にもありますが) setuptools-scm_ に頼ることでしょう:" -#: ../source/discussions/setup-py-deprecated.rst:113 -#, fuzzy -#| msgid "``python -m build``" -msgid "``python -m setuptools-scm``" -msgstr "``python -m build``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" -msgstr "" +msgstr "残りのコマンド群" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" -msgstr "" +msgstr "このガイド文書では、それらコマンド群の代替案について示唆しません:" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" -msgstr "" +msgstr "``alias``" -#: ../source/discussions/setup-py-deprecated.rst:127 -#, fuzzy -#| msgid "``test``" +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" -msgstr "``test``" +msgstr "``bdist``" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" -msgstr "" +msgstr "``bdist_dumb``" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" -msgstr "" +msgstr "``bdist_egg``" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" -msgstr "" +msgstr "``bdist_rpm``" -#: ../source/discussions/setup-py-deprecated.rst:131 -#, fuzzy -#| msgid "build" +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" -msgstr "ビルド" +msgstr "``build``" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" -msgstr "" +msgstr "``build_clib``" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" -msgstr "" +msgstr "``build_ext``" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" -msgstr "" +msgstr "``build_py``" -#: ../source/discussions/setup-py-deprecated.rst:135 -#, fuzzy -#| msgid "``gui-scripts``" +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" -msgstr "``gui スクリプト ``" +msgstr "``build_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" -msgstr "" +msgstr "``clean``" -#: ../source/discussions/setup-py-deprecated.rst:137 -#, fuzzy -#| msgid "``pypinfo``" +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" -msgstr "``pypinfo``" +msgstr "``dist_info``" -#: ../source/discussions/setup-py-deprecated.rst:138 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``easy_install``" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" -msgstr "" +msgstr "``editable_wheel``" -#: ../source/discussions/setup-py-deprecated.rst:140 -#, fuzzy -#| msgid "``pypinfo``" +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" -msgstr "``pypinfo``" +msgstr "``egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:141 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``install``" -#: ../source/discussions/setup-py-deprecated.rst:142 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``install_data``" -#: ../source/discussions/setup-py-deprecated.rst:143 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``install_egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:144 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``install_headers``" -#: ../source/discussions/setup-py-deprecated.rst:145 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" -msgstr "はい (``python -m pip uninstall``)" +msgstr "``install_lib``" -#: ../source/discussions/setup-py-deprecated.rst:146 -#, fuzzy -#| msgid "``gui-scripts``" +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" -msgstr "``gui スクリプト ``" +msgstr "``install_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" -msgstr "" +msgstr "``rotate``" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" -msgstr "" +msgstr "``saveopts``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" -msgstr "" +msgstr "``setopt``" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" -msgstr "" +msgstr "``upload_docs``" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "カスタムコマンドについてはどうでしょうか？" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1484,11 +1604,11 @@ msgstr "" "ことをお勧めします。そのようなツールの例を挙げれば: chuy、 make、 nox もしく" "は tox、 pydoit、 pyinvoke、 taskipy、 そして thx。" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "カスタムビルドステップについてはどうでしょうか？" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " @@ -1499,12 +1619,12 @@ msgstr "" "プは、非推奨にはなっていません。そのようなステップは期待通りに自動的に呼び出" "されるでしょう。" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "``setup.py`` は削除されるべきですか？" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " @@ -1514,11 +1634,11 @@ msgstr "" "しかし、setuptools に対する設定ファイルとして使うことは完全に正当です。:file:" "`setup.py` を修正する必要はないでしょう。" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "``pyproject.toml`` は必須ですか？" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " @@ -1528,14 +1648,14 @@ msgstr "" "スコードツリーのルート部分に :file:`pyproject.toml` ファイルを持つことは **強" "く推奨** されています:" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" "これについては、説明文書の :ref:`setup.py 近代化プロジェクト ` にもっと詳しい説明があります。" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1547,11 +1667,11 @@ msgstr "" "バックの振る舞いは、 :term:`ビルドバックエンド ` が " "setuptools であると仮定することです。" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "どうして？一体全体どういうこと？" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." @@ -1559,16 +1679,16 @@ msgstr "" "ひとつの見方は、setuptools のスコープが、いまや、ビルドバックエンドの役割に限" "定されているということです。" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "これについて、どこでもっと読めますか？" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr ":doc:`setuptools:deprecated/commands`" @@ -2013,29 +2133,33 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," msgstr "" -"プロジェクトの :doc:`コアとなるメタデータ ` " -"(名前・バージョン・作者・その他) を含む ``[project]`` テーブル; 詳しくは、 :" -"doc:`プロジェクトのメタデータを宣言する ` を見てください" +":doc:`コアとなるメタデータ ` (名前・バージョ" +"ン・作者・その他) を含む ``[project]``、" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル。" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" -msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" +"``pyproject.toml`` の設定に関する完全なガイド文書としては、 :ref:`pyproject." +"toml ガイド文書 ` を参照してください。" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "ビルド成果物" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" "`ソースコード配布物 (またはsdist) `" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -2050,7 +2174,7 @@ msgstr "" "り、ローカルでコンパイルを行うステップが必要とされる (C 拡張など) エンドユー" "ザのシステムで役に立つことでしょう。" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" @@ -2058,18 +2182,18 @@ msgstr "" ":ref:`build` パッケージは、次のうちのいずれかを生成するためにあなたの選んだビ" "ルドツールをどのように呼び出すのかを知っています:" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" "あるいは、あなたの選んだツールが、 sdist を生成するためのツール独自のインタ" "フェースを提供しているかもしれません。" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "ビルド済み配布物 (wheels)" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -2082,7 +2206,7 @@ msgstr "" "インストールが素早く行われ、エンドユーザにとってより便利であると言えるでしょ" "う。" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -2097,13 +2221,13 @@ msgstr "" "wheel ファイルが利用できない場合には、 :ref:`pip` のようなツールはソースコー" "ド配布物からのインストールにフォールバックします。" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" "あるいは、あなたの選んだビルドツールが wheel を生成するための独自のインタ" "フェースを提供しているかもしれません。" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " @@ -2113,11 +2237,11 @@ msgstr "" "ら sdist と wheel の両方を作成することです; 上記の例は意図的に特定の動作をさ" "せています。" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "パッケージ配布サービスへアップロードする" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" @@ -2125,17 +2249,17 @@ msgstr "" "ツールの :ref:`twine` の以下のようなコマンドを使って、配布のためにビルド成果" "物を PyPI へアップロードすることができます:" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" "あるいは、あなたの選んだビルドツールにアップロードのための独自のインタフェー" "スが備わっているかもしれません。" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "ダウンロードとインストール" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" @@ -2145,7 +2269,7 @@ msgstr "" "て自分の Python 環境へインストールすることができるようになりました。典型的に" "は、これは、次のようなコマンドを使って :ref:`pip` で行われます:" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -2259,6 +2383,15 @@ msgstr "" "ユーザがインターネットからダウンロードしてインストールするものです。" #: ../source/glossary.rst:64 +#, fuzzy +#| msgid "" +#| "A distribution package is more commonly referred to with the single words " +#| "\"package\" or \"distribution\", but this guide may use the expanded term " +#| "when more clarity is needed to prevent confusion with an :term:`Import " +#| "Package` (which is also commonly called a \"package\") or another kind of " +#| "distribution (e.g. a Linux distribution or the Python language " +#| "distribution), which are often referred to with the single term " +#| "\"distribution\"." msgid "" "A distribution package is more commonly referred to with the single words " "\"package\" or \"distribution\", but this guide may use the expanded term " @@ -2266,7 +2399,8 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" "配布物パッケージは単語ひとつで「パッケージ」や「配布物」と呼ばれることもしば" "しばですが、 :term:`Import Package`(これも通常は単に「パッケージ」と呼ばれま" @@ -2274,11 +2408,11 @@ msgstr "" "でよく単語ひとつの「配布物」と呼ばれるものとの混同を避けるために明確に述べる" "必要がある場合には、本ガイドでは長い方の呼び方を用いることがあります。" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "卵" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -2291,11 +2425,11 @@ msgstr "" "python_eggs>` や `Python Eggs `_ を参照してください。" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "拡張モジュール" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -2309,11 +2443,11 @@ msgstr "" "ジェクトファイル(.so)、Windows上ではDLL(拡張子.pydを与えられる)のPython拡張、" "Jython拡張ではJavaのクラスファイルの形を取る。" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "既知の良好なセット" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -2326,11 +2460,11 @@ msgstr "" "が既知の良好なセット(KGS)であると宣言されます。この用語は、個々の配布物を複数" "組み合わせて構成されるフレームワークやツールキットで共通して用いられます。" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "パッケージ" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." @@ -2338,23 +2472,30 @@ msgstr "" "直接に、あるいは何段階になっても良いが、他のパッケージを組み込んで使うような" "Pythonモジュール。" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 +#, fuzzy +#| msgid "" +#| "An import package is more commonly referred to with the single word " +#| "\"package\", but this guide will use the expanded term when more clarity " +#| "is needed to prevent confusion with a :term:`Distribution Package` which " +#| "is also commonly called a \"package\"." msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" "インポートパッケージは、より普通には「パッケージ」という用語で呼ばれますが、" "本ガイドでは、同様に単に「パッケージ」と呼ばれることが普通である :term:`配布" "物パッケージ `との混同を避けるために必要な場合には、長" "い方の用語を用いることにします。" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "モジュール" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." @@ -2362,11 +2503,11 @@ msgstr "" "Pythonにおけるソースコード再利用の基本的な単位で、 :term:`Pure Module`か :" "term:`Extension Module`の二つのタイプのうちのいずれか。" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "パッケージインデックス" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." @@ -2375,11 +2516,11 @@ msgstr "" "索・ダウンロードが適切か)を自動化するwebインターフェイスを伴った配布物のリポ" "ジトリ。" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "プロジェクト単位の索引" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " @@ -2389,11 +2530,11 @@ msgstr "" "に、:term:`プロジェクト `の単位で示された仲間内または非公式の :term:" "`パッケージ索引 `。" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "プロジェクト" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " @@ -2403,7 +2544,7 @@ msgstr "" "一連のデータもしくはその他のリソース、または、これらの組み合わせで :term:`配" "布物 `として意図的にパッケージされたもの。" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2417,7 +2558,7 @@ msgstr "" "トのソースコードの一番上のディレクトリに :term:`pyproject.toml`や :term:" "`setup.py`または :term:`setup.cfg`のファイルを含む何ものかというものです。" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2430,7 +2571,7 @@ msgstr "" "ひとつまたはより多くの :term:`配布物 `を内包していま" "す。" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -2444,11 +2585,11 @@ msgstr "" "(訳註、「なんとか」とは無関係の別の名前の例)という名前でのみインポート可能な" "パッケージを提供することは可能です。" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "純粋なモジュール" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." @@ -2456,11 +2597,11 @@ msgstr "" "Pythonで書かれていて単一の``.py``ファイル(とおそらくは対応する``.pyc``ファイ" "ルや``.pyo``ファイル)に収められた :term:`モジュール `。" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "Pythonパッケージングオーソリティ(PyPA)" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2477,11 +2618,11 @@ msgstr "" "`Python談話フォーラム `__ で議論を進" "めています。" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "Pythonパッケージインデックス (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " @@ -2491,11 +2632,11 @@ msgstr "" "`Package Index`です。ここから配布物を取り出し、また、配布するためにすべての" "Python開発者に開かれています。" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." @@ -2505,22 +2646,22 @@ msgstr "" "(PyPI)` のためのドメイン名です。2017年にそれまでのドメイン名である ``pypi." "python.org`` を置き換えました。 :ref:`warehouse`を使っています。" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" "ツール不可知論者の :term:`プロジェクト ` 仕様を示すファイル。 :pep:" "`518` で定義。" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "リリース" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." @@ -2528,7 +2669,7 @@ msgstr "" "ある特定の時点における :term:`プロジェクト `のスナップショットで、" "バージョン識別子付きのもの。" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2540,11 +2681,11 @@ msgstr "" "らば、ソースコード配布物とWindowsインストーラ付配布物の両方が利用可能となって" "いるという具合です。" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "要求事項" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2557,17 +2698,23 @@ msgstr "" "`pip` では、「要求事項」とも解釈できる仕様を様々な様式で書くことを許容してい" "ます。詳細については、 :ref:`pip:pip install` の項を参照してください。" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "要求事項識別子" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 +#, fuzzy +#| msgid "" +#| "A format used by :ref:`pip` to install packages from a :term:`Package " +#| "Index`. For an EBNF diagram of the format, see the `pkg_resources." +#| "Requirement `_ entry in the :ref:`setuptools` docs. For " +#| "example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +#| "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" ":term:`パッケージインデックス `からパッケージをインストールす" @@ -2593,12 +2740,12 @@ msgstr "" "Requirementsファイル ` をみてください。" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2805,13 +2952,12 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" -"まとめると、様々な理由からそれ(訳註、ダウンロード統計)の価値が低い上、動作さ" -"せるために犠牲になるものが多いので、限られた資源の効率的な利用にはならないの" -"です。" +"まとめると、様々な理由からその価値が低い上、動作させるために犠牲になるものが" +"多いので、限られた資源の効率的な利用にはならないのです。" #: ../source/guides/analyzing-pypi-package-downloads.rst:40 msgid "Public dataset" @@ -2898,14 +3044,14 @@ msgid "Column" msgstr "カラム" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "説明" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "例" @@ -3308,8 +3454,7 @@ msgstr "" "できます。" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "参考文献" @@ -3555,6 +3700,14 @@ msgid "Packaging and distributing projects" msgstr "パッケージングとプロジェクトの配布" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "期限切れのもの" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -3568,7 +3721,7 @@ msgstr "" "tutorials/installing-packages` ページの内容については慣れ親しんでいるものと仮" "定して進めます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " @@ -3578,7 +3731,7 @@ msgstr "" "しているわけではありません。例えば、バージョン管理や文書化、あるいは試験につ" "いて、手引きとなったりツールを推奨するようなことはありません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -3590,11 +3743,11 @@ msgstr "" "項のいくつかはもはや古くなっているかもしれません。喰い違いがあった場合には、" "Python パッケージングユーザガイドの推奨事項を優先してください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "パッケージングと配布に対する要求事項" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." @@ -3602,11 +3755,11 @@ msgstr "" "最初に、あなたが既に :ref:`パッケージをインストールする際の要求事項 " "` を満たしていることを確実にしてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "\"twine\"をインストールする [1]_:" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " @@ -3616,15 +3769,15 @@ msgstr "" "` にアップロードする( :ref:`後述 ` )ためにこれが必要になるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "あなたのプロジェクトを設定する" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "最初に必要なファイル群" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_ に具体例がありま" "す。" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr ":file:`setup.py` はふたつの主要な機能を提供します。" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -3655,7 +3808,7 @@ msgstr "" "を定義することができます。適切な引数のほとんどについて :ref:`次節 ` で説明します。" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." @@ -3665,7 +3818,7 @@ msgstr "" "るためのコマンドラインインタフェイスです。使用可能なコマンドを一覧するには、 " "``python setup.py --help-commands`` を実行してください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ に使" "用例が出ています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rstとREADME.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` 引数を見て" "ください)。" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_ に例" "が出ています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -3728,11 +3881,11 @@ msgstr "" "を使っているのであれば、あなたはreadmeファイルを :file:`MANIFEST.in` に明記す" "る必要はありません。そうでないなら、明示的に書いてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -3744,7 +3897,7 @@ msgstr "" "動的に追加されるのかも含めて、 :file:`MANIFEST.in` の書き方の詳細については" "「 :ref:`MANIFEST.in の使い方 `」を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3756,17 +3909,17 @@ msgstr "" "sampleproject>`_ では、必要なファイルがすべて 43.0.0およびこれ以降の:ref:" "`setuptools`に含まれているので、マニフェストファイルを削除しています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" ":file:`MANIFEST.in` は、wheelなどのバイナリ配布物には影響を与えません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3782,7 +3935,7 @@ msgstr "" "`GitHubの「オープンソースライセンスを選ぶには」 `_ などのリソースを見ることも、弁護士に相談することもできます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_ に例がでています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "<あなたのパッケージ>" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " @@ -3807,7 +3960,7 @@ msgstr "" "ジュールやパッケージのトップレベルに配置するということが共通の慣習になってい" "ます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " @@ -3817,11 +3970,11 @@ msgstr "" "る `サンプル `_ " "パッケージに例が出ています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "setup() の引数" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " @@ -3831,402 +3984,102 @@ msgstr "" "``setup()`` 関数を含むことです。この関数に与えるキーワード引数は、あなたのプ" "ロジェクトの特定の細部がどのように定義されているかを示すものです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -"もっともよく使われる引数についてこの後解説します。ほとんどのソースコード断片" -"(スニペット)は、`PyPA サンプルプロジェクト `_ の中の `setup.py `_ から取られたもので" -"す。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``名称``" +"いくつかについては、情報がどこか他の場所に移されるまでの一時的な説明が以下に" +"あります。すべてを列挙したものは :doc:`setuptools の説明文書 ` で見つかるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:171 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -"これは、あなたのプロジェクトが :term:`PyPI ` で" -"どこに並べられるかを決めるプロジェクトの名前です。 :pep:`508` に従えば、正当" -"なプロジェクト名は以下の条件を満たさなければなりません：" +"ほとんどのソースコード断片(スニペット)は、`PyPA サンプルプロジェクト " +"`_ の中の `setup.py `_ から取られたものです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:175 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." msgstr "" -"ASCII文字・数字・アンダースコア(``_``)・ハイフン(``-``)・ピリオド(``.``)だけ" -"を含むこと、かつ、" +"あなたのユーザへ互換性情報を伝える方法としてバージョン番号を使うやり方につい" +"ては、 :ref:`バージョンをつける規則を選択するには ` をご覧ください。" #: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "先頭と最後の文字がASCII文字ないし数字であること。" +msgid "``packages``" +msgstr "``packages``" -#: ../source/guides/distributing-packages-using-setuptools.rst:179 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"packages can be listed manually, ``setuptools.find_packages()`` finds them " +"automatically. Use the ``include`` keyword argument to find only the given " +"packages. Use the ``exclude`` keyword argument to omit packages that are " +"not intended to be released and installed." msgstr "" -"プロジェクト名の比較では、大文字小文字を区別せず、また、アンダースコア・ハイ" -"フン・ピリオドは何文字連続していても同じものとして扱います。例えば、あなたが " -"``cool-stuff`` という名前のプロジェクトを登録したなら、利用者がダウンロードし" -"たり依存関係を宣言したりするのに、次に挙げる綴りのどれでも使うことができま" -"す::" +"``packages`` には、あなたのプロジェクトにある :term:`パッケージ ` を子パッケージや孫パッケージなども含めてすべて列挙してください。" +"パッケージは手動で列挙することもできますが、 ``setuptools.find_packages()`` " +"を使えば自動で列挙することができます。 ``include`` キーワード引数を使うと、こ" +"こに与えられた特定のパッケージだけを探索することができます。 ``exclude`` キー" +"ワード引数を使うと、公開したりインストールしたりする意図のないパッケージを除" +"外することができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -"これはあなたのプロジェクトの現在のバージョンで、これがあることであなたのプロ" -"ジェクトのユーザたちが自分が最新版を使っているのかどうかを判断したり、彼ら自" -"身のソフトウェアと組み合わせて試験を行ったバージョンがどれなのかを示したりす" -"ることができるようになります。" +"あなたのプロジェクトに、プロジェクトの一部ではない単一ファイルのPythonモ" +"ジュールがあるなら、 :ref:`setuptools` に知らせるために、そのようなモジュール" +"の(拡張子``.py``を削除した)名前を ``py_modules`` に列挙してください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 -msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" msgstr "" -"バージョンは、あなたが自分のプロジェクトをリリースする度に :term:`PyPI " -"` 上に表示されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" -"See :ref:`Choosing a versioning scheme` for more information on ways to use " -"versions to convey compatibility information to your users." +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." msgstr "" -"あなたのユーザへ互換性情報を伝える方法としてバージョン番号を使うやり方につい" -"ては、 :ref:`バージョンをつける規則を選択するには ` をご覧ください。" +"``install_requires`` は、プロジェクトが動作するために最低限必要な依存関係を指" +"定するのに使われます。プロジェクトが :ref:`pip` でインストールされる場合に" +"は、この指定を見て依存関係(訳註、にある他パッケージ)をインストールするために" +"用いられます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." msgstr "" -"プログラムが動作している間に自分自身のバージョンを知る必要があるのであれば、" -"バージョン番号を :file:`setup.py` とあなたのソースコードの両方に格納しておく" -"のがもっとも単純な方法です。値を複数箇所に書きたくないのであれば、やり方が2,3" -"種類あります。「 :ref:`バージョンを一箇所で管理するには ` 」の「高度な話題」の節を見て下さい。" +"さらなる ``install_requires`` の使い方については :ref:`install_requires対" +"Requirementsファイル ` を参照してくだ" +"さい。" -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``説明``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "あなたのプロジェクトについて、短い説明と長い説明を与えて下さい。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" -"これらの値は、あなたのプロジェクトを公開したときに :term:`PyPI ` に表示されます。 ``pypi.org`` のユーザインタフェイスで" -"は、灰色のバナーに ``description`` を表示し、「プロジェクトの説明」と名付けら" -"れたセクションに ``long_description`` を表示します。" +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" #: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" -"``description`` は、プロジェクト一覧にも表示されます。例えば、https://pypi." -"org/search/?q=jupyter のような検索結果のページや、フロントページの流行プロ" -"ジェクトや新規リリースプロジェクトの一覧や、あなたのアカウントのプロファイル" -"ページ(例えば https://pypi.org/user/jaraco/)の中のあなたがメンテナンスしてい" -"るプロジェクトの一覧に表示されるということです。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" -"``long_description_content_type`` 引数に特に整形しない ``text/plain`` 、" -"`reStructuredText (reST) `_ として解釈される ``text/x-rst`` 、" -"`Markdown `_ の中でもGitHub方" -"言のものとして解釈される ``text/markdown`` のうちのいずれかを与えることで、`" -"コンテンツタイプ `_ を指定することができます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "``url``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "あなたのプロジェクトのホームページのURLを与えてください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "著者について詳しい情報を提供してください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "``ライセンス``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" -"``license`` 引数には、あなたのパッケージがどのライセンスの下で公開されたかを" -"示すこともできますが、これは必須ではなくオプションです。あなたが一般的でよく" -"知られたライセンスを採用するのであれば、 ``分類詞 `` を指定する" -"だけで済ませることができると同時に済ませるべきです。メジャーなオープンソース" -"ライセンスであればどれでも、それを指し示す分類詞が用意されています。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" -"``license`` 引数は、よく知られたライセンスとの違いを示すために使われたり、あ" -"なた自身の独自のライセンスを取り込むために使われたりすることの方がより典型的" -"です。混乱を避けるために、また、組織によってはそのライセンスが認可されていな" -"いためにソフトウェアの使用を避けることがあるので、一般論としては、一般的なよ" -"く知られたライセンスを採用することは良い考えです。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "``分類詞 ``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" -"あなたのプロジェクトを特徴付ける分類詞(classifier)を設定してください。" -"https://pypi.org/classifiers に全部の一覧が出ています。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" -"そのプロジェクトがどのPythonバージョンをサポートしているのかを分類詞リスト" -"(classifiers)で告知することが往々にしてあるのですが、この欄はPyPIでプロジェク" -"トを検索・閲覧する時に使われるためにだけ用意されているのであって、プロジェク" -"トをインストールする時のためのものではありません。本当にPythonのバージョンに" -"制約を付けたい場合には、 :ref:`python_requires`引数を使ってください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" -"パッケージが (誤って) PyPI にアップロードされるのを防ぐには、 ``'Private :: " -"Do Not Upload'`` 分類子を使いましょう。``\"Private ::'`` で始まる分類子を付け" -"られたパッケージを PyPI は常に拒否します。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "``keywords``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "あなたのプロジェクトを説明するキーワードを列挙してください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" -"あなたのプロジェクトに関係する追加的なURLを列挙してください。これは、バグ追跡" -"システムやソースコードリポジトリ、あるいは、パッケージ開発をサポートする場所" -"などをリンクするための場所です。キー文字列をそのままテキストとしてPyPI上に表" -"示されます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 -msgid "``packages``" -msgstr "``packages``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:366 -msgid "" -"Set ``packages`` to a list of all :term:`packages ` in your " -"project, including their subpackages, sub-subpackages, etc. Although the " -"packages can be listed manually, ``setuptools.find_packages()`` finds them " -"automatically. Use the ``include`` keyword argument to find only the given " -"packages. Use the ``exclude`` keyword argument to omit packages that are " -"not intended to be released and installed." -msgstr "" -"``packages`` には、あなたのプロジェクトにある :term:`パッケージ ` を子パッケージや孫パッケージなども含めてすべて列挙してください。" -"パッケージは手動で列挙することもできますが、 ``setuptools.find_packages()`` " -"を使えば自動で列挙することができます。 ``include`` キーワード引数を使うと、こ" -"こに与えられた特定のパッケージだけを探索することができます。 ``exclude`` キー" -"ワード引数を使うと、公開したりインストールしたりする意図のないパッケージを除" -"外することができます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:375 -msgid "``py_modules``" -msgstr "``py_modules``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:381 -msgid "" -"If your project contains any single-file Python modules that aren't part of " -"a package, set ``py_modules`` to a list of the names of the modules (minus " -"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." -msgstr "" -"あなたのプロジェクトに、プロジェクトの一部ではない単一ファイルのPythonモ" -"ジュールがあるなら、 :ref:`setuptools` に知らせるために、そのようなモジュール" -"の(拡張子``.py``を削除した)名前を ``py_modules`` に列挙してください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:387 -msgid "``install_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:393 -msgid "" -"\"install_requires\" should be used to specify what dependencies a project " -"minimally needs to run. When the project is installed by :ref:`pip`, this is " -"the specification that is used to install its dependencies." -msgstr "" -"``install_requires`` は、プロジェクトが動作するために最低限必要な依存関係を指" -"定するのに使われます。プロジェクトが :ref:`pip` でインストールされる場合に" -"は、この指定を見て依存関係(訳註、にある他パッケージ)をインストールするために" -"用いられます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:397 -msgid "" -"For more on using \"install_requires\" see :ref:`install_requires vs " -"Requirements files`." -msgstr "" -"さらなる ``install_requires`` の使い方については :ref:`install_requires対" -"Requirementsファイル ` を参照してくだ" -"さい。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" -"あなたのプロジェクトが特定のバージョンのPythonでないと動作しないのであれば、" -"適切な :pep:`440` バージョン特定文字列で ``python_requires`` 引数を設定してお" -"くことで :ref:`pip` が他のバージョンの `Python` なのに当該プロジェクトをイン" -"ストールしてしまうことがなくなります。例えば、あなたのパッケージが Python 3+ " -"向けのものであれば、このように書いてください：" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "Python 2.6と2.7、そして3.3以上のPython 3用であればこのように書きます::" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "等々。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" -"この機能がサポートされたのは比較的最近のことです。 ``python_requires`` 引数が" -"認識されて適切なメタデータが生成されるためには、あなたのプロジェクトのソース" -"コード配布物やwheels (:ref:`あなたのプロジェクトをパッケージする ` 参照)を24.2.0かそれ以降のバージョンの :ref:`setuptools` でビル" -"ドしなければなりません。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" -"さらに、 :ref:`pip` のバージョン9.0.0かそれ以降のものでなければ " -"``python_requires`` のメタデータを認識しません。これより前のバージョンのpipを" -"使っている場合は、 ``python_requires`` の設定に関わりなくどんなバージョンの" -"Pythonを使っていてもダウンロードやインストールが可能です。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 -msgid "``package_data``" -msgstr "``package_data``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:445 -msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " "package’s implementation, or text files containing documentation that might " @@ -4239,7 +4092,7 @@ msgstr "" "ような説明を含んだテキストファイルであったりします。このようなファイルは" "「パッケージデータ」と呼ばれます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " @@ -4249,7 +4102,7 @@ msgstr "" "イルの相対パス名を列挙したもののマッピングになっていなければなりません。パス" "名はパッケージを含むディレクトリからの相対パスとして解釈されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." @@ -4258,11 +4111,11 @@ msgstr "" "データファイルを追加するには <1setuptools:userguide/datafiles>` を見てくださ" "い。" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "``data_files``" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -4276,7 +4129,7 @@ msgstr "" "す。大抵は、Pythonのパッケージを認識しないような他のプログラムから利用する" "ファイルをインストールする必要がある時に、これが役に立つでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -4297,7 +4150,7 @@ msgstr "" "布物の最上位にある :file:`setup.py` スクリプトに対する相対パスとして解釈され" "ます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." @@ -4305,7 +4158,7 @@ msgstr "" "さらに詳しくは、 :ref:`追加的なファイルをインストールするには ` の中のdistutilsの節を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -4318,12 +4171,12 @@ msgstr "" "unmanageable`` オプション付きの ``python setup.py`` を使わなければなりませ" "ん。" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -4335,69 +4188,15 @@ msgstr "" "いますが、異機種間の互換性を取るためのアプローチとして推奨されるのは :ref:" "`console_scripts` エントリーポイント(後述)を使うことです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" -msgstr "``entry_points``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." -msgstr "" -"あなたのプロジェクト内か依存先のプロジェクトで定義された名前付きのエントリー" -"ポイントをあなたのプロジェクトが提供しているようなプラグインがあればこのキー" -"ワード引数を使って指定してください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:517 -msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" -"詳しくは、:ref:`setup tools` 文書の :ref:`広報する動作 ` の節を見てください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" -"よくあるエントリーポイントとしては、\"console_scipts\" (後述)が挙げられます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" -"``console_script`` :ref:`エントリーポイント ` は、スクリプトインターフェイスを登録するために使ってく" -"ださい。そうすれば、ツールチェーンがそのようなインターフェイスを実際のスクリ" -"プトに変換する作業を肩代わりしてくれます[2]_ 。あなたの :term:`配布物 " -"` をインストールする途中でスクリプトが生成されます。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" -"詳しくは、 :doc:`setuptools 説明文書 ` の中の :doc:`エント" -"リポイント ` を見てください。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 +#: ../source/guides/distributing-packages-using-setuptools.rst:295 msgid "Choosing a versioning scheme" msgstr "バージョン体系を選択する" -#: ../source/guides/distributing-packages-using-setuptools.rst:552 +#: ../source/guides/distributing-packages-using-setuptools.rst:298 msgid "Standards compliance for interoperability" msgstr "相互互換性のための標準的な取り決め" -#: ../source/guides/distributing-packages-using-setuptools.rst:554 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" "Different Python projects may use different versioning schemes based on the " "needs of that particular project, but all of them are required to comply " @@ -4411,11 +4210,11 @@ msgstr "" "pep:`公式のバージョン体系 <440#public-version-identifiers>` の自由度の高い規" "定に合致していなければなりません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "規定に合致したバージョン番号の例を次に示す::" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -4426,15 +4225,15 @@ msgstr "" "様々なバージョン番号の変種的書き方を網羅する :pep:`バージョンの正規化 " "<440#normalization>` のテクニックも定義しています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "方法論の選択" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "意味を伴ったバージョン付与 (推奨)" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " @@ -4444,7 +4243,7 @@ msgstr "" "に従うことが推奨されていますが、リリース前やビルド時のメタデータとしては異な" "るやり方を採用しても良いでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" @@ -4452,22 +4251,22 @@ msgstr "" "意味あるバージョン付与方法の真髄は、MAJOR.MINOR.MAINTENANCE の３段階のバー" "ジョン付与方法で、プロジェクトの作者は以下のように各段階の数字を増やします:" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "APIの変更で互換性を失う時には MAJOR 番号、" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "後方互換性を保ったままで新機能を追加する場合には MINOR を、そして" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" "後方互換性を維持したままのバグ修正の場合には MAINTENANCE を増加させます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -4479,7 +4278,7 @@ msgstr "" "るなら少なくともリリース X.Y が必要だが同じMAJORバージョンを持つならその後の" "リリースでも構わないという書き方を利用することができるようになります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." @@ -4488,11 +4287,11 @@ msgstr "" "ティックバージョニング 2.0.0 仕様書 `_ の第１節から第８" "節までに従うべきです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "日付ベースのバージョン付与" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " @@ -4503,7 +4302,7 @@ msgstr "" "たるリリースで非推奨(deprecation)の警告を出すような場合には適していないかもし" "れません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " @@ -4512,7 +4311,7 @@ msgstr "" "日付ベースのバージョン付与の最大の利点は、バージョン番号を見ただけで基盤に" "なっている機能セットがどれほど古いのかが直截にわかることです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." @@ -4520,11 +4319,11 @@ msgstr "" "日付ベースのバージョン番号は、YEAR.MONTHの形(例えば ``12.04``や``15.10``)をと" "るのが普通です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "一連番号によるバージョン付与" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." @@ -4532,7 +4331,7 @@ msgstr "" "これは最も単純なバージョン付与方法で、リリースのたびに増加する単一の番号で構" "成します。" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " @@ -4542,11 +4341,11 @@ msgstr "" "号によるバージョン番号を見てもAPIの後方互換性に関する情報がほとんど又は全くわ" "からないので、ユーザにとっては追跡するのが最も困難です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "混成型の方法" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -4559,11 +4358,11 @@ msgstr "" "年の中のどのリリースサイクルかを特定することについてはあまり気にしていないと" "いうプロジェクトもあるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "リリース前のバージョン付与方式" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" @@ -4571,23 +4370,23 @@ msgstr "" "どのバージョン付与方式を採用するとしても、ある特定の最終的なリリースの前のリ" "リースが次のような形で公開されることもあるでしょう:" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "零またはそれ以上の dev リリース (\".devN\"という拡張子をつけて表示)" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "零またはそれ以上のalphaリリース (\".aN\"という拡張子をつけて表示)" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "零またはそれ以上のbetaリリース (\".bN\"という拡張子をつけて表示)" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "零またはそれ以上のリリース候補 (\".rcN\"という拡張子をつけて表示)" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." @@ -4595,12 +4394,12 @@ msgstr "" "``pip``や最近のPythonパッケージインストーラでは、依存関係にあるパッケージをイ" "ンストールする際にリリース前のものを無視して含めないのが規定の動作です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "ローカルのバージョン指定子" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -4615,7 +4414,7 @@ msgstr "" "リースの識別子として用いるような :pep:`局所的バージョン識別子 <440#local-" "version-identifiers>` の考え方もサポートします。" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" @@ -4623,11 +4422,11 @@ msgstr "" "ローカルバージョン識別子は、 ``<公的バージョン識別子>+<ローカルバージョンラベ" "ル>`` の形を取ります。例えば::" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "開発モードで作業する" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -4641,7 +4440,7 @@ msgstr "" "集可能状態でインストールされたプロジェクトのPythonソースコードに変更を加える" "と、次にインタープリターのプロセスが開始された時に反映されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" @@ -4649,7 +4448,7 @@ msgstr "" "Pythonのパッケージを「編集可能」/「開発」モードでインストールするには、そのプ" "ロジェクトのルートディレクトリへ移動して、次のコマンドを走らせてください:" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -4665,7 +4464,7 @@ msgstr "" "先のパッケージや ``console_scripts`` に書かれたスクリプトもインストールされま" "す。" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -4678,7 +4477,7 @@ msgstr "" "編集可能モードでインストールしたい場合には、requirements ファイルを次のように" "構成すれば良いでしょう::" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " @@ -4688,7 +4487,7 @@ msgstr "" "います。２行目で、 \"bar\" についてPyPIではなくVCSから充当するようにと依存関" "係を上書きしています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " @@ -4698,7 +4497,7 @@ msgstr "" "ルしたい場合には、 requirements ファイルの先頭にローカルのディレクトリパスを" "置いて次のようになるでしょう::" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -4712,14 +4511,14 @@ msgstr "" "ファイル ` の節を見てください。VCSからのインストール" "については、同書の :ref:`VCSサポート ` の節を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" "最後に、もし依存先パッケージは何もインストールしたくないのであれば、このよう" "にします:" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." @@ -4727,11 +4526,11 @@ msgstr "" "さらに詳しいことを知りたい場合は、 :ref:`setuptools` 文書の :doc:`開発モード " "` の 節を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "プロジェクトをパッケージングする" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -4743,7 +4542,7 @@ msgstr "" "るには、 :term:`配布物 ` (:term:`パッケージ " "`の名前でも知られる) を作成しなければならないでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" @@ -4751,11 +4550,11 @@ msgstr "" "あなたのプロジェクトでwheelsやsdistsをビルドする前に、 ``build`` パッケージを" "インストールする必要があります。" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "ソースコード配布物" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" @@ -4763,7 +4562,7 @@ msgstr "" "少なくとも、 :term:`ソースコード配布物 ` " "を作成するべきです:" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -4777,11 +4576,11 @@ msgstr "" "含まない) であったとしても、 :file:`setup.py` や :file:`setup.cfg` からインス" "トール用メタデータを取り出してビルドする段階を必要とするのです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "Wheels" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -4793,7 +4592,7 @@ msgstr "" "です。wheelを使えば、ソースコード配布物からのインストールに比べてエンドユーザ" "にとって相当素早くインストールすることができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." @@ -4801,7 +4600,7 @@ msgstr "" "あなたのプロジェクトが純Pythonなら、きっとあなたは:ref:`\"純Pythonの" "Wheel\" (後述) `を作成することになるでしょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." @@ -4810,7 +4609,7 @@ msgstr "" "ラットフォーム Wheel* (後述) ` を作成することになるでしょ" "う。" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " @@ -4820,7 +4619,7 @@ msgstr "" "あれば、次のものをあなたの :file:`setup.cfg` ファイルに追加して *ユニバーサ" "ル Wheel* と呼ばれるものを作成するべきです:" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." @@ -4828,11 +4627,11 @@ msgstr "" "あなたのプロジェクトにC言語拡張がなく、かつ、Python 2 および3をサポートしてい" "る場合に限って、この設定を使ってください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "純Python Wheels" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." @@ -4840,12 +4639,12 @@ msgstr "" "*純Python Wheels* は、コンパイル済拡張を含んでおらず、従って単独のPython " "wheelを要求するだけです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "wheelをビルドするには:" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " @@ -4855,7 +4654,7 @@ msgstr "" "へのインストールであればどこでも使えるのでそのように名付けられたwheelをビルド" "します。wheelファイルの名称について詳しいことは :pep:`425` を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." @@ -4863,11 +4662,11 @@ msgstr "" "``--wheel`` か ``--sdist`` を付けずに ``build`` を実行すると、両方のファイル" "が作成されます; 複数のwheelファイルにしたくないときにはこれが便利です。" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "プラットフォームWheels" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." @@ -4876,7 +4675,7 @@ msgstr "" "トフォーム向けのwheelで、大抵の場合は(訳注、特定のプラットフォーム向けにコン" "パイルされた)コンパイル済み拡張を含むためです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " @@ -4886,7 +4685,7 @@ msgstr "" "ビルドされたプラットフォーム上でのみ利用可能であるように命名されたwheelを作成" "します。wheelファイルの命名規則については、 :pep:`425` を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " @@ -4896,11 +4695,11 @@ msgstr "" "け、そして複数のLinuxディストリビューションに対応した ``manylinux*`` のABI向" "けのプラットフォームWheelsをアップロードすることに対応しています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "プロジェクトをPyPIにアップロードする" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " @@ -4910,7 +4709,7 @@ msgstr "" "リに ``dist/`` という新しいディレクトリが作成されます。ここに配布物のファイル" "(群)が置かれます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -4922,7 +4721,7 @@ msgstr "" "たときにはいつでも、PyPIへ送る前に配布物のファイルを再作成する必要があるとい" "うことです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -4934,7 +4733,7 @@ msgstr "" "定すれば試験サイトを使えるかについては、 :ref:`using-test-pypi` を見てくださ" "い。" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -4948,7 +4747,7 @@ msgstr "" "検証しないHTTPSを用いるのであなたのユーザ名とパスワードが 通信経路上で横取り" "される恐れがあって **強く非推奨** の状態になっています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -4965,11 +4764,11 @@ msgstr "" "ファイル群に対して :std:doc:`twine check ` を走らせれば、それを確かめ" "ることができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "アカウントを作成する" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_ アカウントを作成することができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." @@ -4987,7 +4786,7 @@ msgstr "" "次に PyPI の `API トークン `_ を作成して、プロジェクトを安全にアッ" "プロードできるようにしましょう。" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " @@ -4997,7 +4796,7 @@ msgstr "" "トークン `_ を作成してください; これから新しいプロジェクトを作成す" "るわけですから、スコープを特定のプロジェクトに限定しないようにしてください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" @@ -5005,7 +4804,7 @@ msgstr "" "**トークンをコピーして保存するまではページを閉じないでください -- トークンは" "二度と表示されることがありません。**" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" @@ -5013,26 +4812,26 @@ msgstr "" ":file:`$HOME/.pypirc` ファイルを作っておくことで、アップロードするたびにトー" "クンをコピー・ペーストする手間を省くことができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" "**このファイルにはトークンが平文で保存されていることに注意してください。**" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" ":file:`.pypirc` についてさらに詳しく知りたい場合は :ref:`specification " "` を見てください。" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "配布物をアップロードする" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." @@ -5040,7 +4839,7 @@ msgstr "" "アカウントが入手できれば、 :ref:`twine` を使ってあなたの配布物を :term:`PyPI " "` へアップロードすることができます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " @@ -5050,7 +4849,7 @@ msgstr "" "も存在していなくても同じです - もしまだ存在していなければ、最初にリリースが" "アップロードされたときに自動的に作成されます。" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." @@ -5058,7 +4857,7 @@ msgstr "" "２回目やそれ以降のリリースで PyPI が要求するのは、新しいリリースのバージョン" "番号が先行するすべてのリリースとは異なるものであることだけです。" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -5070,7 +4869,7 @@ msgstr "" "たのパッケージのアップロードは成功です。あなたのプロジェクトがサイト上に表示" "されるまでには1,2分の時間がかかるかもしれません。" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -5082,19 +4881,6 @@ msgstr "" "のインストールを規定動作にする案 `_ にあるように、この部分の変更を検討しています。" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" -"特に、\"console_script\" を使うと Windows では ``.exe`` ファイルを生成します" -"が、これはOSが特別なケースとして ``.exe`` ファイルを必要とするからです。 " -"``PATHEXT`` や :pep:`Windows向けPythonランチャー <397>` のようなスクリプトを" -"実行する機能によって多くの場合にスクリプトが使われますが、しかし、いつでも使" -"えるわけではありません。" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "古いバージョンのPython へのサポートをやめる" @@ -5239,19 +5025,10 @@ msgstr "" "うに、バージョンの範囲や除外のルールを指定することができます。" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "例::" +msgid "Examples:" +msgstr "例:" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " @@ -5261,11 +5038,11 @@ msgstr "" "の中で行えます。 ``python_requires`` 引数に設定した内容に基づいて ``Requires-" "Python`` メタデータの値が挿入されます。" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "3. 公開の前にメタデータを検証する" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." @@ -5273,7 +5050,7 @@ msgstr "" "Python のソースコードパッケージ (あなたがダウンロードしたzipファイルやtar.gz" "ファイル) の中には、PKG-INFO という名前のテキストファイルがあります。" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " @@ -5283,15 +5060,15 @@ msgstr "" "を作成する時に一緒に作成されます。その内容は、一連のキーと値の組み合わせで、" "キーは Pypa 標準メタデータフォーマットの一部です。" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "生成されたファイルの内容はこのようになっています:" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "パッケージを公開する前に、以下のことが適切かどうかを検証してください。" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." @@ -5299,18 +5076,18 @@ msgstr "" "アップグレードが正しく終われば、Metadata-Version の値が 1.2 かそれ以上になっ" "ているはずです。" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" "Requires-Python フィールドが設定されていて、setup.py でのあなたの指定に一致し" "ているはずです。" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "4. Twineを使って公開する" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." @@ -5318,15 +5095,15 @@ msgstr "" "動作が速いことを別にしてもTwineには数多くの利点があり、今ではパッケージを公開" "するためのメソッドとしてサポートされています。" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "少なくとも1.9以上の最新のTwineを使うようにしてください。" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "Pythonリリースをサポートから外す" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." @@ -5334,13 +5111,13 @@ msgstr "" "Requires-Python メタデータ付きでパッケージを公開しさえすれば、次回以降の更新" "の際にPython ランタイムをサポートから外すことができるようになります。" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" "自動フォールバックが正しく動作するためには、この順番で行わなければなりませ" "ん。" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." @@ -5348,7 +5125,7 @@ msgstr "" "例えば、 Requires-Python: \">=2.7\" の状態であなたのパッケージのバージョン " "1.0.0 を公開したとしましよう。" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -5365,11 +5142,17 @@ msgid "Hosting your own simple repository" msgstr "あなた自身の単純なリポジトリをホストする" #: ../source/guides/hosting-your-own-index.rst:8 +#, fuzzy +#| msgid "" +#| "If you wish to host your own simple repository [1]_, you can either use a " +#| "software package like :doc:`devpi ` or you can use simply " +#| "create the proper directory structure and use any web server that can " +#| "serve static files and generate an autoindex." msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" "あなた自身の単純なリポジトリ [1]_ をホストしたいのであれば、 :doc:`devpi " "` のようなソフトウェアパッケージを使うこともできますし、単にウェ" @@ -5759,7 +5542,7 @@ msgstr "" "たツールチェーンと互換性がないかもしれません。" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "Spack" @@ -5916,6 +5699,7 @@ msgstr "" "ようになりました。" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "例:" @@ -5950,8 +5734,8 @@ msgstr "" "い:" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." -msgstr "pipx については、 https://pypa.github.io/pipx/ でもっと学べます。" +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "pipx については、 https://pipx.pypa.io/ でもっと学べます。" #: ../source/guides/installing-using-linux-tools.rst:5 msgid "Installing pip/setuptools/wheel with Linux Package Managers" @@ -6181,7 +5965,7 @@ msgid "Create and activate a virtual environment" msgstr "仮想環境を作成し活性化する" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "pip の準備をする" @@ -6257,15 +6041,15 @@ msgstr "第三者のパッケージ群を使う時には仮想環境を用いる #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -"仮想環境を作成するには、あなたのプロジェクトのディレクトリへ行って ``venv`` " +"仮想環境を作成するには、プロジェクトのディレクトリへ行って次のようなコマンド" "を実行してください。これによって、ローカルの ``.venv`` フォルダに新しい仮想環" "境ができるでしょう:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." @@ -6273,14 +6057,14 @@ msgstr "" "二つ目の引数は、仮想環境を作成するべき場所の指定です。一般的には、プロジェク" "トのルートディレクトリに ``.venv`` という名前で作成します。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" "``venv`` は仮想的な Python を ``.venv`` ディレクトリの中にインストールするで" "しょう。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." @@ -6288,11 +6072,11 @@ msgstr "" "仮想環境のディレクトリは、 ``.gitignore`` やその類似物を使ってバージョン管理" "システムから除外しておくべきです。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "仮想環境を活性化する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -6304,7 +6088,7 @@ msgstr "" "と、その仮想環境に特有の ``python`` と ``pip`` の実行ファイルがシェルの " "``PATH`` 変数に追加されます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" @@ -6312,7 +6096,7 @@ msgstr "" "仮想環境が activate されたことを確認するには、 Python インタープリタの場所を" "確かめましょう:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" @@ -6320,7 +6104,7 @@ msgstr "" "仮想環境が active である間は、上記のコマンドは ``.venv`` ディレクトリを含む" "ファイルパスを出力することでしょう、つまり以下のようになって終了します:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " @@ -6330,11 +6114,11 @@ msgstr "" "します。これによって、あなたの Python アプリケーションからそのパッケージをイ" "ンポートして使用することができるようになります。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "仮想環境を非活性化 する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" @@ -6342,7 +6126,7 @@ msgstr "" "プロジェクトを切り替えたい、あるいは、仮想環境から離脱したい時は、仮想環境を " "``deactivate`` してください:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." @@ -6351,11 +6135,11 @@ msgstr "" "もし、新しいシェル窓を開いて、そこで仮想環境を使いたい時は、再活性化 " " してください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "仮想環境を再活性化 する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " @@ -6364,7 +6148,7 @@ msgstr "" "既存の仮想環境を活性化 したい場合は、仮想環境の活性化に関する上述" "のやり方に従ってください。新しい仮想環境を作成する必要はありません。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." @@ -6372,7 +6156,7 @@ msgstr "" ":ref:`pip` は Python の参照モデルとなるパッケージマネージャです。仮想環境内で" "パッケージのインストールや更新に用いられます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " @@ -6382,14 +6166,14 @@ msgstr "" "pip`` のような追加のパッケージをインストールしなければならないかもしれませ" "ん。以下のようにすると pip が最新版であることを確実にすることができます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" "それから、ユーザサイトには最新版の pip がインストールされているはずです:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" @@ -6397,15 +6181,15 @@ msgstr "" "Windows 用の Python インストーラは pip を含んでいます。以下のようにすると " "pip が最新版であることを確実にすることができます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "その後、pip が最新版になっているはずです:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "pip を使ってパッケージをインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." @@ -6414,11 +6198,11 @@ msgstr "" "す。パッケージをインストールするには ``pip install`` コマンドを使ってくださ" "い。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "パッケージをインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" @@ -6426,18 +6210,18 @@ msgstr "" "例として、 :term:`Python Package Index (PyPI)` から `Requests`_ ライブラリを" "インストールしてみましょう:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" "pip が requests とその依存先パッケージをすべてダウンロードしてインストールす" "るはずです:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "特定のバージョンのパッケージをインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " @@ -6447,21 +6231,21 @@ msgstr "" "ジョンを指定してインストールすることができます。例えば、 ``requests`` の特定" "のバージョンをインストールするなら:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "requests の最新の ``2.x`` リリースをインストールするには:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" "``--pre`` フラグを使ってパッケージのリリース前のバージョンをインストールする" "には:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "(パッケージの) extra 部分をインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" @@ -6470,11 +6254,11 @@ msgstr "" "前を角括弧([, ])の中に書くことで pip にインストールするように指示することがで" "きます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "ソースコードからパッケージをインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" @@ -6483,7 +6267,7 @@ msgstr "" "えば、 ``google-auth`` ディレクトリの中にあるソースコードをインストールするに" "は:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -6495,11 +6279,11 @@ msgstr "" "コードを修正すると、再インストールしなくても、すぐにインストール済みのパッ" "ケージに反映されます。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "バージョン管理システムからインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" @@ -6507,7 +6291,7 @@ msgstr "" "pip は、バージョン管理システムから直接に、パッケージをインストールすることが" "できます。例えば、git リポジトリから直接にインストールするには:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." @@ -6515,11 +6299,11 @@ msgstr "" "サポートされているバージョン管理システムや文法について、詳しくは :ref:`VCS サ" "ポート ` の pip の説明文書を見てください。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "ローカルアーカイブからインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" @@ -6528,7 +6312,7 @@ msgstr "" "wheel や tar ファイル) をローカルに持っているなら、 pip でそこから直接にイン" "ストールすることができます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " @@ -6538,7 +6322,7 @@ msgstr "" "て、:term:`Python パッケージインデックス ` を全" "く利用しないということも可能です:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " @@ -6547,11 +6331,11 @@ msgstr "" "この機能は、限定的なインターネット接続しか得られないシステムでパッケージをイ" "ンストールする際や、配布物パッケージの出自を厳密に管理したい時には便利です。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "他のインデックスサイトからインストールする" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" @@ -6560,7 +6344,7 @@ msgstr "" "ころからパッケージをダウンロードしたいのであれば、 ``--index-url`` オプション" "でできます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " @@ -6570,12 +6354,12 @@ msgstr "" "ンデックスを同時に使いたいのであれば、 ``--extra-index-url`` オプションででき" "ます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "パッケージを更新する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" @@ -6584,11 +6368,11 @@ msgstr "" "例えば、 ``requests`` とその依存先パッケージの最新版をインストールしたいのな" "ら:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "requirements ファイルを使う" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " @@ -6599,7 +6383,7 @@ msgstr "" "列挙しておくことができます。例えば、 :file:`requirements.txt` を下記を含むよ" "うに作成しておいて:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" @@ -6607,11 +6391,11 @@ msgstr "" "このファイルに書いてあるパッケージを全てインストールするようにと、 ``-r`` オ" "プションを与えることで pip に指示します:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "依存関係を凍結する" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" @@ -6619,11 +6403,11 @@ msgstr "" "Pip では、 ``freeze`` コマンドを使うことで、インストール済みの全パッケージの" "バージョン付きのリストを取り出すことができます:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "それは、次に挙げるようなパッケージ指定子のリストを出力します:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -7200,13 +6984,12 @@ msgstr ":ref:`配布パッケージ `" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" -msgstr ":ref:`ビルド依存関係を宣言する `" +msgid ":ref:`pyproject-build-system-table`" +msgstr ":ref:`pyproject-build-system-table`" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr ":doc:`pip:reference/build-system/pyproject-toml`" @@ -7291,11 +7074,11 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" -"``[project]`` テーブルで許される内容の完全な仕様については、 :ref:`プロジェク" -"トのメタデータを宣言する ` を読んでください。" +"``[project]`` テーブルで許される内容の完全な仕様については、 :ref:" +"`` を読んでください。" #: ../source/guides/modernize-setup-py-project.rst:169 msgid "How to handle dynamic metadata?" @@ -7343,11 +7126,11 @@ msgstr "" "トのソースコードツリーに `setup.py` を残すことは完全に問題のないことです。こ" "のファイルの最小限の姿はこのようになります:" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr ":ref:`プロジェクトのメタデータを宣言する `" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr ":doc:`setuptools:build_meta`" @@ -7920,10 +7703,8 @@ msgstr "" "いう理由のひとつであることを詳しく説明すること :)" #: ../source/guides/packaging-binary-extensions.rst:236 -#, fuzzy -#| msgid "mention the module lifecycle" msgid "Extension module lifecycle" -msgstr "モジュールのライフサイクルに言及してください" +msgstr "拡張モジュールのライフサイクル" #: ../source/guides/packaging-binary-extensions.rst:238 #: ../source/guides/packaging-binary-extensions.rst:244 @@ -7931,27 +7712,23 @@ msgstr "モジュールのライフサイクルに言及してください" #: ../source/guides/packaging-binary-extensions.rst:256 #: ../source/guides/packaging-binary-extensions.rst:376 msgid "FIXME: This section needs to be fleshed out." -msgstr "" +msgstr "FIXME: この節には肉付けが必要です。" #: ../source/guides/packaging-binary-extensions.rst:242 -#, fuzzy -#| msgid "mention the challenges of shared static state and subinterpreters" msgid "Implications of shared static state and subinterpreters" -msgstr "shared static state やサブインタプリタの試みについて言及すること" +msgstr "shared static state やサブインタプリタの影響" #: ../source/guides/packaging-binary-extensions.rst:248 msgid "Implications of the GIL" -msgstr "" +msgstr "GIL の影響" #: ../source/guides/packaging-binary-extensions.rst:254 -#, fuzzy -#| msgid "mention the memory allocation APIs in 3.4+" msgid "Memory allocation APIs" -msgstr "3.4+ におけるメモリ割り当てについて言及すること" +msgstr "メモリを割り当てる API 群" #: ../source/guides/packaging-binary-extensions.rst:262 msgid "ABI Compatibility" -msgstr "" +msgstr "ABI の互換性" #: ../source/guides/packaging-binary-extensions.rst:264 msgid "" @@ -7960,6 +7737,11 @@ msgid "" "module against one version of Python, it is only guaranteed to work with the " "same minor version of Python and not with any other minor versions." msgstr "" +"CPython の C 言語 API は、マイナーリリース (3.2, 3.3, 3.4 等) 間の ABI の互換" +"性を保証しません。これが意味するところは、典型的には、Python のあるバージョン" +"向けに拡張モジュールをビルドした時にマイナーバージョンまで同じ Python での動" +"作が保証されるだけであって、他のマイナーバージョンについては保証されないとい" +"うことです。" #: ../source/guides/packaging-binary-extensions.rst:270 msgid "" @@ -7969,6 +7751,12 @@ msgid "" "Wheels containing extensions built against the stable ABI use the ``abi3`` " "ABI tag, to reflect that they're compatible with all Python 3.x versions." msgstr "" +"Python 3.2 では、Python の C 言語 API のよく定義されたサブセットとして " +"Limited API を導入しました。Limited API が必要とするシンボル群は、Python 3.x " +"のすべてのバージョンを通じて互換性を保つことが保証された \"Stable ABI\" を形" +"成しています。Stable ABI を使ってビルドされた拡張部分を含む Wheel は、Python " +"3.x のすべてのバージョンで互換性を保っていることを反映するために ``abi3`` と" +"いう ABI タグを使用します。" #: ../source/guides/packaging-binary-extensions.rst:277 msgid "" @@ -7976,6 +7764,9 @@ msgid "" "information about the API / ABI stability guarantees, how to use the Limited " "API and the exact contents of the \"Limited API\"." msgstr "" +"CPython の :doc:`C 言語 API の安定性 ` のページには、 " +"API/ABI の安定性保証、つまり、 Limited API をどのように使うのかや \"Limited " +"API\" の正確な内容について詳しい情報があります。" #: ../source/guides/packaging-binary-extensions.rst:283 msgid "Building binary extensions" @@ -7983,22 +7774,13 @@ msgstr "バイナリ拡張をビルドする" #: ../source/guides/packaging-binary-extensions.rst:285 msgid "FIXME: Cover the build-backends available for building extensions." -msgstr "" +msgstr "FIXME: Cover the build-backends available for building extensions." #: ../source/guides/packaging-binary-extensions.rst:288 msgid "Building extensions for multiple platforms" msgstr "複数のプラットフォーム向けに拡張モジュールをビルドする" #: ../source/guides/packaging-binary-extensions.rst:290 -#, fuzzy -#| msgid "" -#| "If you plan to distribute your extension, you should provide :term:" -#| "`wheels ` for all the platforms you intend to support. For most " -#| "extensions, this is at least one package per Python version times the " -#| "number of OS and architectures you support. These are usually built on " -#| "continuous integration (CI) systems. There are tools to help you build " -#| "highly redistributable binaries from CI; these include :ref:" -#| "`cibuildwheel` and :ref:`multibuild`." msgid "" "If you plan to distribute your extension, you should provide :term:`wheels " "` for all the platforms you intend to support. These are usually " @@ -8008,12 +7790,9 @@ msgid "" msgstr "" "あなたが自分の書いた拡張モジュールを配布するつもりがあるなら、あたながサポー" "トしようと思うすべてのプラットフォーム向けに :term:`wheels ` を準備す" -"るべきでしょう。ほとんどの拡張モジュールにおいて、Python のバージョン毎にサ" -"ポートする予定の OS とアーキテクチャの数を掛け算した分に少なくともひとつの" -"パッケージが必要であるということになります。通常はこれらを継続的インテグレー" -"ション (CI) システム上でビルドします。:ref:`cibuildwheel` や :ref:" -"`multibuild` のような CI から再配布が非常にやりやすいバイナリをビルドするのを" -"補助するツールの存在が知られています。" +"るべきです。通常はこれらを継続的インテグレーション (CI) システム上でビルドし" +"ます。:ref:`cibuildwheel` や :ref:`multibuild` のような CI から再配布が非常に" +"やりやすいバイナリをビルドするのを補助するツールの存在が知られています。" #: ../source/guides/packaging-binary-extensions.rst:296 msgid "" @@ -8021,6 +7800,9 @@ msgid "" "intend to support. This means that the number of wheels you need to build is " "the product of::" msgstr "" +"ほとんどの拡張部分向けに、すべてのサポートするつもりのあるプラットフォーム用" +"の wheel をビルドする必要があるでしょう。これが意味するところは、ビルドする必" +"要のある wheel 群の数が次のような掛け算になるだろうということです::" #: ../source/guides/packaging-binary-extensions.rst:302 msgid "" @@ -8030,6 +7812,12 @@ msgid "" "eliminating one dimension of the matrix. It also removes the need to " "generate new wheels for each new minor version of Python." msgstr "" +"CPython の :ref:`Stable ABI ` を使うことで、準備する必要" +"のある wheel の数を大いに減らすことに役立つでしょう、というのは、あるプラット" +"フォーム上の単一の wheel が Python のすべてのマイナーバージョンで使える; つま" +"り、マトリクスの次元をひとつ削除することになるからです。さらに、新しいマイ" +"ナーバージョンの Python が出現するたびに新たに wheel を生成する必要もなくなり" +"ます。" #: ../source/guides/packaging-binary-extensions.rst:309 msgid "Binary extensions for Windows" @@ -8044,7 +7832,7 @@ msgid "" "extensions, install `Visual Studio Community Edition `__ - any recent version is fine." msgstr "" -"バイナリ拡張をびるどできるようになる前に、適切なコンパイラが利用できるように" +"バイナリ拡張をビルドできるようになる前に、適切なコンパイラが利用できるように" "なっていることを保証しなければなりません。Windows 上でCPython インタプリタを" "ビルドするのに Visual C が使われていますが、互換性のあるバイナリ拡張をビルド" "する時にも同じコンパイラを使うべきです。バイナリ拡張のためのビルド環境を構築" @@ -8140,10 +7928,14 @@ msgid "" "using the build-backend and upload it to PyPI using :doc:`twine `." msgstr "" +"PyPI を通じてバイナリ拡張を公開する時にも、純 Python のパッケージを公開すると" +"きと同じアップロードのメカニズムを使います。その拡張の wheel をビルドバックエ" +"ンドを使ってビルドし、 :doc:`twine ` を使って PyPI にアップロー" +"ドするということです。" #: ../source/guides/packaging-binary-extensions.rst:365 msgid "Avoid binary-only releases" -msgstr "" +msgstr "バイナリだけのリリースを避ける" #: ../source/guides/packaging-binary-extensions.rst:367 msgid "" @@ -8153,12 +7945,15 @@ msgid "" "certain Linux distributions that build from source within their own build " "systems for the distro package repositories." msgstr "" +"バイナリ拡張を公開する時にはそれをビルドする際に用いたソースコードも公開する" +"ことが強く推奨されています。こうすることで、必要であればユーザがその拡張を" +"ソースコードからビルドすることができます。特筆すべきことに、 Linux ディストリ" +"ビューションの中には、そのディストロ向けのパッケージリポジトリの独自のビルド" +"システム内でソースコードからビルドすることを要求するものがあるのです。" #: ../source/guides/packaging-binary-extensions.rst:374 -#, fuzzy -#| msgid "cover weak linking" msgid "Weak linking" -msgstr "weak linking について書くこと" +msgstr "弱いリンキング " #: ../source/guides/packaging-binary-extensions.rst:379 msgid "Additional resources" @@ -8231,11 +8026,11 @@ msgstr "" "`C++ で cpython の拡張モジュールを書く `_" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "名前空間パッケージをパッケージする" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -8249,23 +8044,23 @@ msgstr "" "ジュールを分離できるようにすることができます。例えば、下に示すようなパッケー" "ジ構造であれば:" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "そして、このパッケージを自分のソースコード中で使うにはこのようにする::" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" "そうすることで、これらのサブパッケージ群を別々のふたつの配布物に分割すること" "ができます:" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" "それぞれのサブパッケージは、今や、個別にインストール・使用・バージョン管理す" "ることができます。" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -8284,21 +8079,19 @@ msgstr "" "mynamespace_subpackage_a as subpackage_a`` のようにインポートすることさえでき" "ます) 。" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "名前空間パッケージを作成する" -#: ../source/guides/packaging-namespace-packages.rst:62 -#, fuzzy -#| msgid "" -#| "There are currently three different approaches to creating namespace " -#| "packages:" +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" -msgstr "現在、名前空間パッケージを作るには３個の異なる手法があります:" +msgstr "" +"現在、名前空間パッケージを作るには２個の異なる手法がありますが、後者は使わな" +"い方が良いとされています:" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -8311,23 +8104,21 @@ msgstr "" "ポートすればよくて ``pip`` でインストールするのであれば、これが推奨される方法" "です。" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" +"`レガシー名前空間パッケージ群 `_ を使ってくださ" +"い。これは`pkgutil 型の名前空間パッケージ `_ および `pkg_resources 型の名前空間パッケージ `_ から構成されています。" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "組み込みの名前空間パッケージ" -#: ../source/guides/packaging-namespace-packages.rst:75 -#, fuzzy -#| msgid "" -#| "Python 3.3 added **implicit** namespace packages from :pep:`420`. All " -#| "that is required to create a native namespace package is that you just " -#| "omit :file:`__init__.py` from the namespace package directory. An example " -#| "file structure:" +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -8335,11 +8126,12 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" "Python 3.3 では :pep:`420` から **暗黙の** 名前空間パッケージを追加しました。" -"組み込みの名前空間パッケージを作成するのに必要なことは、名前空間パッケージの" -"ディレクトリから :file:`__init__.py` を取り除くことだけです。ファイル構造の例" -"はこちら:" +"ネイティブな名前空間パッケージを作成するのに必要なことは、名前空間パッケージ" +"のディレクトリから :file:`__init__.py` を取り除くことだけです。ファイル構造の" +"例はこちら (:ref:`ソースコードレイアウト ` に従いま" +"す):" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -8351,7 +8143,7 @@ msgstr "" "ずれかの配布物でこれを忘れると、名前空間の論理が破綻して、他のサブパッケージ" "をインポートすることができなくなります。" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -8359,24 +8151,29 @@ msgid "" "exclusions or inclusions of packages yourself, this is possible to be " "configured in the top-level :file:`pyproject.toml`:" msgstr "" +"``src-layout`` ディレクトリ構造によって、ほとんどの :term:`ビルドバックエン" +"ド ` が自動的にパッケージ群を発見できるようになります。もっと" +"情報が欲しい場合は :ref:`src-layout-vs-flat-layout` を見てください。しかしな" +"がら、パッケージの包含・除外を自分自身で管理したいのであれば、トップレベル" +"の :file:`pyproject.toml` を設定することで可能です:" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" -msgstr "" +msgstr "同じことが :file:`setup.cfg` で達成できます:" -#: ../source/guides/packaging-namespace-packages.rst:127 -#, fuzzy -#| msgid ":file:`setup.cfg`" +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" -msgstr ":file:`setup.cfg` ファイル" +msgstr "または :file:`setup.py` ファイル:" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" +":ref:`setuptools` は、デフォルトでは暗黙の名前空間パッケージを探してディレク" +"トリ構造を探索します。" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." @@ -8384,7 +8181,7 @@ msgstr "" "ふたつの名前空間パッケージの完全な動作例は、 `組み込みの名前空間パッケージの" "使用例プロジェクト `_ にあります。" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -8396,13 +8193,11 @@ msgstr "" "ケージを使用し、 Python 2 と Python 3 の両方をサポートしなければならない配布" "物では pkgutil型名前空間パッケージを使うことが可能です。" -#: ../source/guides/packaging-namespace-packages.rst:156 -#, fuzzy -#| msgid "Using namespace packages" +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" -msgstr "namespaceパッケージを用いるやり方" +msgstr "伝統的な名前空間パッケージ群" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -8410,13 +8205,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -8428,11 +8223,11 @@ msgstr "" "りません。同じ名前空間向けにパッケージを提供するような複数の配布物で、異なる" "手法を用いることは推奨されません。" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "pkgutil 型名前空間パッケージ" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -8446,7 +8241,7 @@ msgstr "" "しれません。これは、互換性のレベルが最も高くなるアプローチとして推奨されてい" "ます。" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" @@ -8454,12 +8249,9 @@ msgstr "" "pkgutil 型の名前空間パッケージを作成するには、その名前空間パッケージ用に :" "file:`__init__.py` ファイルを準備する必要があります:" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 #, fuzzy -#| msgid "" -#| "The :file:`__init__.py` file for the namespace package needs to contain " -#| "**only** the following:" msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" @@ -8467,15 +8259,9 @@ msgstr "" "名前空間パッケージ用の :file:`__init__.py` ファイルは、次に示すもの **だけ** " "を含んでいる必要があります:" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 #, fuzzy -#| msgid "" -#| "**Every** distribution that uses the namespace package must include an " -#| "identical :file:`__init__.py`. If any distribution does not, it will " -#| "cause the namespace logic to fail and the other sub-packages will not be " -#| "importable. Any additional code in :file:`__init__.py` will be " -#| "inaccessible." msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -8488,7 +8274,7 @@ msgstr "" "う。 :file:`__init__.py` に他のコードを追加しても、それはアクセスできないもの" "となるでしょう。" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." @@ -8496,11 +8282,11 @@ msgstr "" "pkgutil 型の名前空間パッケージのふたつの動作例が `pkgutil 型名前空間を例示す" "るプロジェクト `_ にあります。" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "pkg_resources 型名前空間パッケージ" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -8519,7 +8305,7 @@ msgstr "" "作成する時には、異なる手法が相互に互換ではないために既存パッケージを移植しよ" "うとすることが推奨されていないので、この手法を採用し続けることを推奨します。" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" @@ -8527,7 +8313,7 @@ msgstr "" "pkg_resources 型名前空間パッケージを作成するには、名前空間パッケージ用の :" "file:`__init__.py` を準備する必要があります:" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" @@ -8535,7 +8321,7 @@ msgstr "" "いくつかの古めの推奨では、次のような名前空間パッケージ用 :file:`__init__.py` " "を使うように言っています:" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -8550,7 +8336,7 @@ msgstr "" "パッケージとしては ``install_requires`` を通じて setuptools に明示的に依存す" "ると示しておくべきです。" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" @@ -8558,7 +8344,7 @@ msgstr "" "最後に、それぞれの配布物は :file:`setup.py` の :func:`~setuptools.setup` 向け" "に ``namespace_packages`` 引数を準備しておく必要があります。例えば:" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -8936,7 +8722,6 @@ msgstr "" #: ../source/guides/section-build-and-publish.rst:3 #, fuzzy -#| msgid "Building and Publishing Projects:" msgid "Building and Publishing" msgstr "プロジェクトをビルドして公開する:" @@ -8946,7 +8731,6 @@ msgstr "" #: ../source/guides/section-install.rst:3 #, fuzzy -#| msgid "Installation format" msgid "Installation" msgstr "インストールフォーマット" @@ -8954,7 +8738,15 @@ msgstr "インストールフォーマット" msgid "Single-sourcing the package version" msgstr "パッケージのバージョンを１箇所で管理する" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" @@ -8962,7 +8754,7 @@ msgstr "" "プロジェクトのバージョン番号をたったひとつの真実の場所で管理するテクニックは" "たくさん存在しています:" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" @@ -8971,7 +8763,7 @@ msgstr "" "( `pip setup.py `_ での) 例は" "こちら::" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " @@ -8981,7 +8773,7 @@ msgstr "" "ルに置くことで同じことを達成できています (\"package\" をパッケージをインポー" "トする際の名前で置き換えてください) :" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." @@ -8989,7 +8781,7 @@ msgstr "" "setuptools 61.0.0 のリリースの時点では、プロジェクトの :file:`pyproject." "toml` ファイルの中にバージョンを動的に指定することができます。" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." @@ -8997,7 +8789,7 @@ msgstr "" "``attr:`` ディレクティブを含む装飾的な設定指示子が、 :file:`setup.py` 向けの" "パラメータとしてはサポートされていないことに注意してください。" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." @@ -9005,7 +8797,7 @@ msgstr "" "外部のビルドツールを使う場合は、両方の場所(ロケーション)を更新できるようなも" "の、あるいは、両方のサイトから使える API を提供しているものを使いましょう。" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -9018,7 +8810,7 @@ msgstr "" "`commitizen `_, `zest.releaser `_." -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " @@ -9028,7 +8820,7 @@ msgstr "" "ル (例えば :file:`version.py`) を作って :file:`setup.py` からそれを読み取っ" "て ``exec`` で値を変数に取り込むと良いでしょう。" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." @@ -9036,7 +8828,7 @@ msgstr "" "このテクニックを使っている例: `warehouse `_ 。" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." @@ -9044,7 +8836,7 @@ msgstr "" "単純に ``VERSION`` という名前のテキストファイルに値を書いておいて、 :file:" "`setup.py` とプロジェクトのソースコードの両方から読み込みます。" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." @@ -9052,7 +8844,7 @@ msgstr "" "このテクニックを使う利点は、Python に限定されたやり方ではないということです。" "どんなツールでもバージョン番号を読み取ることができます。" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " @@ -9062,7 +8854,7 @@ msgstr "" "リの配布物に含まれているように気を付けてください (例えば :file:`MANIFEST.in` " "に ``include VERSION`` を追加しておくなど)。" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -9077,7 +8869,7 @@ msgstr "" "ストール済みのプロジェクトのバージョン番号をこの API で取り込むには次のように" "します::" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " @@ -9087,7 +8879,7 @@ msgstr "" "データだけであって、現在インポートされているソースコードについて知っていると" "は限らないことに注意してください。" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" @@ -9098,7 +8890,7 @@ msgstr "" "``install_requires`` に ``importlib-metadata`` を書いておかなければなりませ" "ん::" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" @@ -9106,7 +8898,7 @@ msgstr "" "``importlib.metadata`` に対するもっと古い (かつ、より非効率な) 代替策は、 " "``setuptools`` が提供する ``pkg_resources`` API です::" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." @@ -9115,7 +8907,7 @@ msgstr "" "``pkg_resources`` を使っているなら、プロジェクトの ``install_requires`` のリ" "ストには必ず ``setuptools`` が入っていないといけません。" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." @@ -9123,7 +8915,7 @@ msgstr "" "このテクニックを使っている例: `setuptools `_." -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." @@ -9131,7 +8923,7 @@ msgstr "" "``sample/__init__.py`` で ``__version__`` に値を設定して、 :file:`setup.py` " "から ``sample`` をインポートしましょう。" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " @@ -9142,7 +8934,7 @@ msgstr "" "なパッケージは :file:`setup.py` が実行される時点ではまだインストールされてい" "ない可能性が高いので、失敗するであろうということに注意してください。" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -10111,9 +9903,6 @@ msgstr "``MANIFEST.in`` を使ってソースコード配布物にファイル #: ../source/guides/using-manifest-in.rst:7 #, fuzzy -#| msgid "" -#| "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." msgid "" "The information on this page has moved to :doc:`setuptools:userguide/" "miscellaneous` in the setuptools documentation." @@ -10207,16 +9996,19 @@ msgid "Setting up TestPyPI in :file:`.pypirc`" msgstr ":file:`.pypirc` ファイルで TestPyPI を設定する" #: ../source/guides/using-testpypi.rst:75 +#, fuzzy +#| msgid "" +#| "If you want to avoid entering your username, you can configure TestPyPI " +#| "in your :file:`$HOME/.pypirc`:" msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" "(毎回 TestPyPI の) ユーザ名を入力するのが面倒なら、 :file:`$HOME/.pypirc` " "ファイルに TestPyPI 関連の設定をしておくことができます:" #: ../source/guides/writing-pyproject-toml.rst:5 #, fuzzy -#| msgid "Creating pyproject.toml" msgid "Writing your ``pyproject.toml``" msgstr "pyproject.toml を作成する" @@ -10277,7 +10069,6 @@ msgstr "" #: ../source/guides/writing-pyproject-toml.rst:45 #, fuzzy -#| msgid "Declaring build system dependencies" msgid "Declaring the build backend" msgstr "ビルドシステムの依存関係を宣言する" @@ -10304,7 +10095,6 @@ msgstr "" #: ../source/guides/writing-pyproject-toml.rst:94 #, fuzzy -#| msgid "The complete list of keys allowed in the ``[project]`` table are:" msgid "The rest of this guide is devoted to the ``[project]`` table." msgstr "``[project]`` テーブルで許容されるキーの完全なリストは次のとおりです:" @@ -10334,95 +10124,147 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``名称``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +#, fuzzy +#| msgid "" +#| "Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-" +#| "``), and/or periods (``.``), and" +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"ASCII文字・数字・アンダースコア(``_``)・ハイフン(``-``)・ピリオド(``.``)だけ" +"を含むこと、かつ、" + +#: ../source/guides/writing-pyproject-toml.rst:136 +#, fuzzy +#| msgid "" +#| "Comparison of project names is case insensitive and treats arbitrarily-" +#| "long runs of underscores, hyphens, and/or periods as equal. For example, " +#| "if you register a project named ``cool-stuff``, users will be able to " +#| "download it or declare a dependency on it using any of the following " +#| "spellings::" +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"プロジェクト名の比較では、大文字小文字を区別せず、また、アンダースコア・ハイ" +"フン・ピリオドは何文字連続していても同じものとして扱います。例えば、あなたが " +"``cool-stuff`` という名前のプロジェクトを登録したなら、利用者がダウンロードし" +"たり依存関係を宣言したりするのに、次に挙げる綴りのどれでも使うことができま" +"す::" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 #, fuzzy -#| msgid "The keywords for the project." msgid "Put the version of your project." msgstr "プロジェクトに関するキーワード。" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy -#| msgid "Using requirements files" msgid "Dependencies and requirements" msgstr "requirements ファイルを使う" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "``dependencies``/``optional-dependencies``" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "``requires-python``" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 #, fuzzy -#| msgid "Creating the package files" msgid "Creating executable scripts" msgstr "パッケージファイルを作成する" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -10430,17 +10272,14 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 #, fuzzy -#| msgid "" -#| "TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -#| "``[project.entry-points]``)" msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." @@ -10448,81 +10287,130 @@ msgstr "" "TOML_ 型: table (``[project.scripts]`` ・ ``[project.gui-scripts]`` ・ " "``[project.entry-points]``)" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 #, fuzzy -#| msgid "Configuring your project" msgid "About your project" msgstr "あなたのプロジェクトを設定する" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "``authors``/``maintainers``" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``説明``" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "``readme``" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," -msgstr "" +#: ../source/guides/writing-pyproject-toml.rst:310 +#, fuzzy +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr ":rfc:`Github 流の Markdown <7764#section-3.2>` を指定する ``GFM``" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +#, fuzzy +#| msgid "" +#| "`reStructuredText `_ (without " +#| "Sphinx extensions)" +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" +"`reStructuredText `_ (Sphinx 拡張な" +"し)" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 #, fuzzy -#| msgid "You can see the contents of the generated file like this:" msgid "You can also specify the format explicitly, like this:" msgstr "生成されたファイルの内容はこのようになっています:" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``ライセンス``" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +#, fuzzy +#| msgid "" +#| "The ``license`` argument is more typically used to indicate differences " +#| "from well-known licenses, or to include your own, unique license. As a " +#| "general rule, it's a good idea to use a standard, well-known license, " +#| "both to avoid confusion and because some organizations avoid software " +#| "whose license is unapproved." +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" +"``license`` 引数は、よく知られたライセンスとの違いを示すために使われたり、あ" +"なた自身の独自のライセンスを取り込むために使われたりすることの方がより典型的" +"です。混乱を避けるために、また、組織によってはそのライセンスが認可されていな" +"いためにソフトウェアの使用を避けることがあるので、一般論としては、一般的なよ" +"く知られたライセンスを採用することは良い考えです。" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``分類詞 ``" + +#: ../source/guides/writing-pyproject-toml.rst:365 #, fuzzy -#| msgid "" -#| "Provide a list of classifiers that categorize your project. For a full " -#| "listing, see https://pypi.org/classifiers/." msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." @@ -10530,47 +10418,82 @@ msgstr "" "あなたのプロジェクトを特徴付ける分類詞(classifier)を設定してください。" "https://pypi.org/classifiers に全部の一覧が出ています。" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +#, fuzzy +#| msgid "" +#| "Although the list of classifiers is often used to declare what Python " +#| "versions a project supports, this information is only used for searching " +#| "& browsing projects on PyPI, not for installing projects. To actually " +#| "restrict what Python versions a project can be installed on, use the :ref:" +#| "`python_requires` argument." +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"そのプロジェクトがどのPythonバージョンをサポートしているのかを分類詞リスト" +"(classifiers)で告知することが往々にしてあるのですが、この欄はPyPIでプロジェク" +"トを検索・閲覧する時に使われるためにだけ用意されているのであって、プロジェク" +"トをインストールする時のためのものではありません。本当にPythonのバージョンに" +"制約を付けたい場合には、 :ref:`python_requires`引数を使ってください。" + +#: ../source/guides/writing-pyproject-toml.rst:397 +#, fuzzy +#| msgid "" +#| "To prevent a package from being uploaded to PyPI, use the special " +#| "``'Private :: Do Not Upload'`` classifier. PyPI will always reject " +#| "packages with classifiers beginning with ``\"Private ::'``." +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"パッケージが (誤って) PyPI にアップロードされるのを防ぐには、 ``'Private :: " +"Do Not Upload'`` 分類子を使いましょう。``\"Private ::'`` で始まる分類子を付け" +"られたパッケージを PyPI は常に拒否します。" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "``urls``" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 #, fuzzy -#| msgid "For example:" msgid "A full example" msgstr "例:" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -10629,12 +10552,6 @@ msgstr "" #: ../source/index.rst:44 #, fuzzy -#| msgid "" -#| "The :doc:`Overview of Python Packaging ` explains Python " -#| "packaging and its use when preparing and distributing projects. This " -#| "section helps you build understanding about selecting the tools and " -#| "processes that are most suitable for your use case. It includes what " -#| "packaging is, the problems that it solves, and key considerations." msgid "" "The :doc:`overview` explains Python packaging and its use when preparing and " "distributing projects. This section helps you build understanding about " @@ -10719,7 +10636,6 @@ msgstr "" #: ../source/index.rst:85 #, fuzzy -#| msgid "Deploying Python applications" msgid ":doc:`discussions/deploying-python-applications`" msgstr "Pythonで書かれたアプリケーションを配置(deploy)する" @@ -10729,7 +10645,6 @@ msgstr "" #: ../source/index.rst:89 #, fuzzy -#| msgid "References" msgid "Reference" msgstr "参考文献" @@ -10743,9 +10658,6 @@ msgstr "" #: ../source/index.rst:92 #, fuzzy -#| msgid "" -#| "Additionally, there is a list of :doc:`other projects ` " -#| "maintained by members of the Python Packaging Authority." msgid "" "The list of :doc:`other projects ` maintained by members of " "the Python Packaging Authority." @@ -10806,10 +10718,6 @@ msgstr "ビルド" #: ../source/key_projects.rst:37 #, fuzzy -#| msgid "" -#| "`Docs ` | `Issues `__ " -#| "| `GitHub `__ | `PyPI `__" msgid "" ":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI ` from the " -#| "standard library in Python 3.12." msgid "" "Consequently, :ref:`distutils` was deprecated in Python 3.10 by :pep:`632` " "and has been :doc:`removed ` from the standard library " @@ -11014,12 +10915,6 @@ msgstr "" #: ../source/key_projects.rst:146 #, fuzzy -#| msgid "" -#| "Hatch is a unified command-line tool meant to conveniently manage " -#| "dependencies and environment isolation for Python developers. Python " -#| "package developers use Hatch and its build backend Hatchling to " -#| "configure, version, specify dependencies for, and publish packages to " -#| "PyPI. Its plugin system allows for easily extending functionality." msgid "" "Hatch is a unified command-line tool meant to conveniently manage " "dependencies and environment isolation for Python developers. Python package " @@ -11139,12 +11034,6 @@ msgstr "" #: ../source/key_projects.rst:209 #, fuzzy -#| msgid "" -#| "Pipenv is a project that aims to bring the best of all packaging worlds " -#| "to the Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:" -#| "`virtualenv` into one single toolchain. It can autoimport ``requirements." -#| "txt`` and also check for CVEs in `Pipfile` using `safety `_." msgid "" "Pipenv is a project that aims to bring the best of all packaging worlds to " "the Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:" @@ -11195,9 +11084,10 @@ msgid "pipx" msgstr "pipx" #: ../source/key_projects.rst:236 +#, fuzzy msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" @@ -11212,10 +11102,10 @@ msgstr "" "るためのツールです。" #: ../source/key_projects.rst:247 +#, fuzzy msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" ":doc:`説明文書 ` | `課題リスト `__ | `GitHub `, " -#| "especially ones that have dependencies on other packages." msgid "" "Setuptools (which includes ``easy_install``) is a collection of enhancements " "to the Python distutils that allow you to more easily build and distribute " @@ -11299,12 +11183,12 @@ msgstr "" "project/trove-classifiers/>`__" #: ../source/key_projects.rst:293 +#, fuzzy msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" "trove-classifiers は、`PyPI における分類子 `_ " "の正統な源泉で、ユーザがそのニーズに即したプロジェクトを PyPI でよりうまく探" @@ -11312,7 +11196,7 @@ msgstr "" "`_ のに使います。" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -11334,11 +11218,11 @@ msgstr "" "pypa/trove-classifiers/issues>`_ に、提案された分類子に関する議論や新しい分類" "子が欲しいという要求に関する議論が公開されています。" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "twine" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -11348,7 +11232,7 @@ msgstr "" "`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -11363,16 +11247,12 @@ msgstr "" "らであり、動作が速く安全であるからであり、保守されているからであり、動作が信" "頼できるからです。" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "virtualenv" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 #, fuzzy -#| msgid "" -#| ":doc:`Docs ` | `Issues `__ | `GitHub `__ | " -#| "`PyPI `__" msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `GitHub `__ | " "`PyPI `__" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 #, fuzzy -#| msgid "" -#| "virtualenv is a tool which uses the command-line path environment " -#| "variable to create isolated Python :term:`Virtual Environments `, much as :ref:`venv` does. virtualenv provides additional " -#| "functionality, compared to :ref:`venv`, by supporting Python 2.7 and by " -#| "providing convenient features for configuring, maintaining, duplicating, " -#| "and troubleshooting the virtual environments. For more information, see " -#| "the section on :ref:`Creating and using Virtual Environments`." msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -11408,11 +11280,11 @@ msgstr "" "を提供します。さらなる情報については、:ref:`仮想環境を作って使う ` の節を見てください。" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "Warehouse" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" @@ -11420,7 +11292,7 @@ msgstr "" "`説明文書 `__ | `課題リスト `__ | `GitHub `__" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " @@ -11430,11 +11302,11 @@ msgstr "" "構成しているコードベース。 `pypi.org `_ にホストされていま" "す。 :ref:`pip` がダウンロードする際のデフォルトのソースです。" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "wheel" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -11444,7 +11316,7 @@ msgstr "" "`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " @@ -11455,7 +11327,7 @@ msgstr "" "にも、wheel ファイルを作成しインストールするためのコマンドラインユーティリ" "ティを提供します。" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -11469,15 +11341,15 @@ msgstr "" "のためのメタデータを確認し、 wheel とメタデータがパッケージないの外部共有ライ" "ブラリに正しくリンクしインクルードするように修正する機能を提供します。" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "非 PyPA プロジェクト" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "buildout" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `PyPI `__ | `GitHub `__" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -11499,15 +11371,15 @@ msgstr "" "buildout の設定を作っておけば、後で同じソフトウェアを再生成することができま" "す。" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "conda" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr ":doc:`説明文書 `" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -11521,7 +11393,7 @@ msgstr "" "て配布している配布物で、とりわけ通常ならバイナリ拡張のインストールが難しいと" "される Windows 用に配布しています。" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " @@ -11531,7 +11403,7 @@ msgstr "" "ケージ管理・仮想環境管理・バイナリ拡張のデプロイメントの観点ではこれらのツー" "ルを合わせたような機能を提供します。" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -11553,11 +11425,11 @@ msgstr "" "skeleton.html>`__ は、 PyPI から持ってきた Python パッケージのメタデータを修" "正することで conda がインストールできるものにするためのツールです。" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "devpi" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" @@ -11565,7 +11437,7 @@ msgstr "" "`説明文書 `__ | :gh:`課題リスト ` | `PyPI `__" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -11577,11 +11449,11 @@ msgstr "" "プロクシキャッシュの機能を持ちます。devpi は閲覧と検索が可能なwebインタフェイ" "スも備えています。" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "enscons" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" @@ -11589,7 +11461,7 @@ msgstr "" ":gh:`ソースコード ` | :gh:`課題リスト ` | `PyPI `__" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -11608,11 +11480,11 @@ msgstr "" "パッケージング機能を追加しています。 Enscons は、 :ref:`pip` で自動的にビルド" "された sdist や、enscons から独立した wheel をビルドすることを支援します。" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "Hashdist" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" @@ -11620,7 +11492,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -11638,15 +11510,12 @@ msgstr "" "パッケージ配布物をステートレスでキャッシュ可能かつ分岐可能にすることを目指し" "ています。一部の研究者が使っていますが、2016 年以降は保守されていません。" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 #, fuzzy -#| msgid "" -#| "`Docs `__ | `GitHub `__" msgid "" "`Docs `__ | `GitHub `__" @@ -11654,18 +11523,18 @@ msgstr "" "`説明文書 `__ | `GitHub `__" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "meson-python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" @@ -11673,7 +11542,7 @@ msgstr "" "`説明文書 `__ | `GitHub " "`__" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -11685,17 +11554,16 @@ msgstr "" "ステムとして使うことを可能にします。これは C 言語を含む広範囲の言語をサポート" "しており、最も複雑なビルド設定を記述することが可能になります。" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "multibuild" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy -#| msgid "`GitHub `__" msgid "`GitHub `__" msgstr "`GitHub `__" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" @@ -11705,11 +11573,11 @@ msgstr "" "Python :term:`wheels ` をビルドしテストする一揃いの CI スクリプトで" "す。 :ref:`cibuildwheel` も見てください。" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "pdm" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11717,7 +11585,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." @@ -11725,7 +11593,7 @@ msgstr "" "PDM は近代的な Python パッケージ管理ソフトです。 :pep:`621` で定義されている" "形でプロジェクトのメタデータを :term:`pyproject.toml` に保存します。" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11733,7 +11601,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -11747,11 +11615,11 @@ msgstr "" "file:`__main__.py` を伴う注意深く構築された zip ファイルであり、単に cp すれ" "ば Python アプリケーションを配置 (deploy) できるように設計されています。" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "pip-tools" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -11779,11 +11647,11 @@ msgstr "" "ること (これは現時点の :ref:`pip` にはない機能です) 、プログラムが従うべき制" "約条件の層を作成することができます。" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "piwheels" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" @@ -11791,7 +11659,7 @@ msgstr "" "`Web サイト `__ | :doc:`説明文書 ` | `GitHub `__" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -11804,11 +11672,11 @@ msgstr "" "pip が PyPI に加えて piwheel.org を追加のインデックスとして使うように予め設定" "されています。" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "poetry" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11816,7 +11684,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -11831,11 +11699,11 @@ msgstr "" "を提供します。依存関係に関するメタデータをローカルにキャッシュすることでイン" "ストールや依存関係解決のユーザ体験を高速化しようとしています。" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "pypiserver" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" @@ -11843,7 +11711,7 @@ msgstr "" "`GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -11859,11 +11727,11 @@ msgstr "" "`pip` でダウンロード・インストールすることもできます。 pypiserver を用いる組" "織では、通常は pypiserver と PyPI の両方からパッケージをダウンロードします。" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "PyScaffold" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11871,7 +11739,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -11887,11 +11755,11 @@ msgstr "" "PyScaffold は、また、既存のプロジェクトにおいてもパッケージングをより簡単にす" "るために使用することができます。" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "scikit-build" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 #, fuzzy -#| msgid "" -#| "Scikit-build is an improved build system generator for CPython C/C++/" -#| "Fortran/Cython extensions that integrates with :ref:`setuptools`, :ref:" -#| "`wheel` and :ref:`pip`. It internally uses `cmake `__ (available on PyPI) to provide better support for " -#| "additional compilers, build systems, cross compilation, and locating " -#| "dependencies and their associated build requirements. To speed up and " -#| "parallelize the build of large projects, the user can install `ninja " -#| "`__ (also available on PyPI)." msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -11930,18 +11789,13 @@ msgstr "" "project/ninja>`__ (これも PyPI から入手可能) をインストールすることも可能で" "す。" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 #, fuzzy -#| msgid "scikit-build" msgid "scikit-build-core" msgstr "scikit-build" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 #, fuzzy -#| msgid "" -#| "`Docs `__ | `GitHub " -#| "`__ | `PyPI `__" msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 #, fuzzy -#| msgid "" -#| "Scikit-build is an improved build system generator for CPython C/C++/" -#| "Fortran/Cython extensions that integrates with :ref:`setuptools`, :ref:" -#| "`wheel` and :ref:`pip`. It internally uses `cmake `__ (available on PyPI) to provide better support for " -#| "additional compilers, build systems, cross compilation, and locating " -#| "dependencies and their associated build requirements. To speed up and " -#| "parallelize the build of large projects, the user can install `ninja " -#| "`__ (also available on PyPI)." msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ (これも PyPI から入手可能) をインストールすることも可能で" "す。" -#: ../source/key_projects.rst:662 +#: ../source/key_projects.rst:661 msgid "shiv" msgstr "shiv" -#: ../source/key_projects.rst:664 +#: ../source/key_projects.rst:663 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11991,7 +11836,7 @@ msgstr "" "`説明文書 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -12003,7 +11848,7 @@ msgstr "" "ティです。このツールの第一の目標は、Python アプリケーションとコマンドライン" "ツールを素早く簡便に配布できるようにすることです。" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__ | `スライド `__" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -12034,7 +11879,7 @@ msgstr "" "で科学分野の高パフォーマンスアプリケーションを素早くビルドするために設計され" "ました。" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." @@ -12042,11 +11887,11 @@ msgstr "" "Spack は (まだ) PyPI にありませんが、 GitHub からクローンした直後にインストー" "ル作業なしで使用できます。" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "zest.releaser" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -12069,15 +11914,15 @@ msgstr "" "ド管理の側でリリースタグを挿入したり、新しいパッケージを PyPI にアップロード" "することを自動化することができます。" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "標準ライブラリ内のプロジェクト群" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "ensurepip" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" @@ -12085,7 +11930,7 @@ msgstr "" "`説明文書 `__ | `課題リス" "ト `__" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -12097,11 +11942,11 @@ msgstr "" "ほとんどの場合にはエンドユーザがこのモジュールを使うことはなく、どちらかと言" "えば Python 配布物のビルドの際に使われるでしょう。" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "venv" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" @@ -12109,7 +11954,7 @@ msgstr "" "`説明文書 `__ | `課題リスト " "`__" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -12818,7 +12663,6 @@ msgstr ":pep:`518` を追加した。 (:pr:`281`)" #: ../source/overview.rst:3 #, fuzzy -#| msgid "An Overview of Packaging for Python" msgid "Overview of Python Packaging" msgstr "Python におけるパッケージングに関する概要" @@ -13163,12 +13007,6 @@ msgstr "" #: ../source/overview.rst:163 #, fuzzy -#| msgid "" -#| "Python's native packaging is mostly built for distributing reusable code, " -#| "called libraries, between developers. You can piggyback **tools**, or " -#| "basic applications for developers, on top of Python's library packaging, " -#| "using technologies like :doc:`setuptools entry_points `." msgid "" "Python's native packaging is mostly built for distributing reusable code, " "called libraries, between developers. You can piggyback **tools**, or basic " @@ -13836,29 +13674,17 @@ msgstr "" "い言語を使うということのために Python プログラマが支払う小さな代償であること" "に気づくことでしょう。" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "バイナリ配布物のフォーマット" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" -"バイナリ配布物のフォーマット (:term:`wheel `) は、元々は :pep:`427` で" -"定義されました。仕様の現在のバージョンはここにあります。" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "要約" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -"この PEP は、 Python 向けコンパイル済みパッケージの \"wheel\" と呼ばれる" -"フォーマットについて記述しています。" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -13875,76 +13701,28 @@ msgstr "" "報を保存しつつ、サイトパッケージを置くべき場所に標準の 'unxip' ツールで単純に" "アンパックすればインストールできます。" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "PEP の受諾" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" -"この PEP は受諾され、定義された wheel のバージョンが 1.0 に2013年2月16日に " -"Nick Coghlan によって更新されました" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "理論的根拠" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" -"Python には sdist よりも簡単にインストールすることができるパッケージフォー" -"マットが必要です。 Python の sdist パッケージは、ソースコードをビルドしたりイ" -"ンストールしたり再コンパイルしたりするために任意のコードを実行し、そうするこ" -"とで新しい virtualenv 環境にインストールできるように、 distutiles と " -"setuptools によるビルドシステムによって定義され、かつ、これらのツールを必要と" -"します。このようなビルドとインストールを合成したシステムは動作が遅く、維持管" -"理が困難であり、ビルドシステムとインストーラの双方における技術革新を阻害しま" -"す。" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" -"Wheel は、ビルドシステムとインストーラの間により単純なインタフェイスを提供す" -"ることで、これらの問題を癒すことを試みます。 wheel バイナリパッケージのフォー" -"マットは、インストーラがビルドシステムについて知らなくても済むようにし、何度" -"もインストールするとしてもコンパイルにかかる時間を節約できるようにし、また、" -"インストール先の環境にビルドシステムをインストールする必要を取り除きます。" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "詳細" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "wheel の 'distribution-1.0-py32-none-any.whl' をインストールする" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "Wheel によるインストールは、概念上、ふたつの段階から構成されています:" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "アンパックする。" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "``distribution-1.0.dist-info/WHEEL`` をパースします。" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." @@ -13952,23 +13730,23 @@ msgstr "" "インストーラが Wheel のバージョンと互換であることを確認します。マイナーバー" "ジョンが大きければ警告し、メジャーバージョンが大きければ処理を中断します。" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" "もし、 Root-Is-Purelib == 'true' であれば、アーカイブを purelib (site-" "packages) へアンパックします。" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" "そうでなければ、アーカイブを platlib (site-packages) へアンパックします。" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "広げる。" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." @@ -13976,7 +13754,7 @@ msgstr "" "アンパックされたアーカイブは、 ``distribution-1.0.dist-info/`` と (データ部分" "があれば) ``distribution-1.0.data/`` を含んでいます。" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -13990,7 +13768,7 @@ msgstr "" "レクトリは、目的地となるディレクトリパスの辞書になっています。初期状態でサ" "ポートされているパスは ``distutils.command.install`` から取り込まれます。" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." @@ -13998,17 +13776,17 @@ msgstr "" "もし該当するならば、 ``#!python`` から始まるスクリプト群が適切なインタープリ" "タを指し示すように更新します。" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" "``distribution-1.0.dist-info/RECORD`` をインストール先のディレクトリパスに更" "新します。" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "空の ``distribution-1.0.data`` ディレクトリを削除します。" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" @@ -14017,15 +13795,15 @@ msgstr "" "トーラは、 RECORD で言及されていなくても .pyc ファイルを削除できるほどに賢く" "あるべきです。)" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "推奨されるインストーラの機能" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "``#!python`` を書き換えます。" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -14038,7 +13816,7 @@ msgstr "" "書き換えられます。アーカイブが Windows で作成されていれば、 Unix でのインス" "トーラがこのようなファイルに +x ビットを追加設定する必要があるでしょう。" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." @@ -14046,11 +13824,11 @@ msgstr "" "``b'#!pythonw'`` と書く慣習も許容されています。 ``b'#!pythonw'`` というのはコ" "ンソール版ではなくて GUI 版のスクリプトであることを示します。" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "スクリプトラッパを生成します。" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " @@ -14060,15 +13838,15 @@ msgstr "" "随伴していないことが普通でしょう。 Windows インストーラは、インストールする際" "にそれらを追加したくなるかもしれません。" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "推奨されるアーカイバの機能" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "アーカイブの末尾に ``.dist-info`` を置くこと。" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -14080,15 +13858,15 @@ msgstr "" "タを修正することができる点を含む、 ZIP のいくつかの潜在的に興味深いトリックを" "使うことができるようになります。" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "ファイルフォーマット" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "ファイル名の慣習" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." @@ -14097,27 +13875,27 @@ msgstr "" "グ})?-{python タグ}-{abi タグ}-{プラットフォームタグ}.whl <{distribution}-" "{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl>`` です。" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "配布物" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "配布物の名前、例えば 'django' や 'pyramid' 。" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "配布物のバージョン、例えば 1.0 。" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "ビルドタグ" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -14132,7 +13910,7 @@ msgstr "" "を ``str`` として解釈して第２要素とするような要素数が２個のタプルとして解釈さ" "れ、指定されていない場合には空欄のタプルとして解釈されます。" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " @@ -14142,7 +13920,7 @@ msgstr "" "使って manylinux で配布物をビルドしている場合のように、ビルド環境に変化があっ" "たためにバイナリ配布物を再ビルドする時です。" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -14154,7 +13932,7 @@ msgstr "" "からの参照を必要とするようなケースとしては、セキュリティ上の脆弱性を解決しよ" "うとする場合がよくあるケースです。" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -14165,33 +13943,33 @@ msgstr "" "ビルドする際にビルド番号を使う **べきではありません** 。そのような場合には、" "代わりに **新しい配布物バージョン** が作成されるべきです。" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "言語の実装とバージョンタグ" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "例えば、 'py27' ・ 'py2' ・ 'py3' 。" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "abi タグ" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "例えば、 'cp33m' ・ 'abi3' ・ 'none' 。" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "プラットフォームタグ" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "例えば、 'linux_x86_64' ・ 'any' 。" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -14203,7 +13981,7 @@ msgstr "" "で動作し、 ABI を持たず (即ち純 Python) 、任意の CPU アーキテクチャで動作する" "ということです。" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " @@ -14213,11 +13991,11 @@ msgstr "" "す。互換性タグは、インタープリタに対するそのパッケージの基本的な要求事項を表" "現しており、 PEP 425 に詳しく書かれています。" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "エスケープとユニコード" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " @@ -14227,7 +14005,7 @@ msgstr "" "で、この文字は構成要素の中に出現してはなりません。これは次のように取り扱われ" "ます:" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -14245,11 +14023,8 @@ msgstr "" "きていなければなりませんが、しかし、それはこの仕様の初期のバージョンで許され" "ていたからです。" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 #, fuzzy -#| msgid "" -#| "Version numbers should be normalised according to :pep:`440`. Normalised " -#| "version numbers cannot contain ``-``." msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " @@ -14258,7 +14033,7 @@ msgstr "" "バージョン番号は、 :pep:`440` に従って正規化されなければなりません。正規化済" "みのバージョン番号は ``-`` を含んでいてはなりません。" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." @@ -14266,7 +14041,7 @@ msgstr "" "残りの構成要素は、 ``-`` 文字を含んでいてはいけないので、エスケープ処理を行う" "必要がありません。" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " @@ -14276,7 +14051,7 @@ msgstr "" "いことを検証しなければなりませんが、これは、もし含んでいれば結果として生成さ" "れたファイルが正しく処理されないかもしれないからです。" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " @@ -14286,7 +14061,7 @@ msgstr "" "ファイル名をサポートするように更新されるまでに幾らかの時間がかかるかもしれま" "せんが、しかし、この仕様ではサポートされているのです。" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " @@ -14297,11 +14072,11 @@ msgstr "" "せんが、このエンコーディングは ZIP の仕様でも Python の ``zipfile`` の仕様で" "も、共にサポートされています。" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "ファイルの内容" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " @@ -14311,7 +14086,7 @@ msgstr "" "え、 {version} の部分を例えば `1.0.0`` のようなバージョン番号で置き換えた " "wheel ファイルの内容は次のもので構成されています:" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " @@ -14322,11 +14097,11 @@ msgstr "" "います。通常は、 ``purelib`` や ``platlib`` はいずれも ``site-packages`` で" "す。" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "``{distribution}-{version}.dist-info/`` はメタデータを含んでいます。" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -14339,7 +14114,7 @@ msgstr "" "るような、空ではないそれぞれのインストールスキームに対応したディレクトリを含" "みます。" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " @@ -14349,7 +14124,7 @@ msgstr "" "ストール時のスクリプトラッパの生成や ``#!python`` 書き換えといった利点を活用" "するために、正確に ``b'#!python'`` で始まっていなければなりません。" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." @@ -14357,7 +14132,7 @@ msgstr "" "``{distribution}-{version}.dist-info/METADATA`` は、バージョン 1.1 またはそれ" "以上のフォーマットのメタデータです。" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" @@ -14365,11 +14140,11 @@ msgstr "" "``{distribution}-{version}.dist-info/WHEEL`` は、同様のキー:バリュー形式で表" "現されたアーカイブそのものに関するメタデータです::" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "``Wheel-Version`` は、Wheel の仕様のバージョン番号です。" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." @@ -14377,7 +14152,7 @@ msgstr "" "``Generator`` は、そのアーカイブを作成したソフトウェアの名前で、バージョン番" "号を付加しても構いません。" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " @@ -14387,7 +14162,7 @@ msgstr "" "トールされるべきものであれば true で、そうでなければ platlib へインストールさ" "れます。" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." @@ -14395,13 +14170,13 @@ msgstr "" "``Tag`` は、 wheel の拡張互換性タグで、例の中ではファイル名の ``py2.py3-none-" "any`` の部分です。" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" "``Build`` は、ビルドナンバーで、もしビルドナンバーがなければ省略されます。" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " @@ -14411,7 +14186,7 @@ msgstr "" "ければ警告するべきですし、 Wheel-Version のメジャーバージョンがサポートしてい" "るものより大きい場合にはフェイルするべきです。" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." @@ -14419,11 +14194,11 @@ msgstr "" "Wheel は複数のバージョンの Python を跨いでも動作するように意図されたインス" "トール用のフォーマットですが、通常は .pyc ファイルを含みません。" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "Wheel は、 setup.py ないし setup.cfg を含みません。" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -14435,12 +14210,12 @@ msgstr "" "wininst や egg バイナリフォーマットが提供する機能の上位互換のレイアウトを提案" "します。" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr ".dist-info ディレクトリ" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." @@ -14448,7 +14223,7 @@ msgstr "" "Wheel の .dist-info ディレクトリは、最低限でも METADATA ・ WHEEL ・RECORD を" "含みます。" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." @@ -14456,12 +14231,12 @@ msgstr "" "METADATA はパッケージのメタデータで、 sdists のルートディレクトリにある PKG-" "INFO と同じフォーマットで記述されます。" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" "WHEEL は、パッケージをビルドする部分に特化した wheel のメタデータです。" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -14476,18 +14251,18 @@ msgstr "" "的に強いハッシュ値に依存しているので、ハッシュ計算のアルゴリズムは sha256 以" "上でなければならず、特に md5 とsha1 は許されません。" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "PEP 376 の INSTALLER と REQUESTED はアーカイブに含まれません。" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" "RECORD.jws は、デジタル署名のために使われます。これについては RECORD では触れ" "られません。" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." @@ -14495,7 +14270,7 @@ msgstr "" "自分の wheel ファイルを S/MIME 署名でセキュアにすることを好む人は、 RECORD." "p7s を使うことができます。これについては RECORD では触れられません。" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -14507,11 +14282,11 @@ msgstr "" "イブの中のいずれかのファイルが RECORD にリストされていないか、または、正しく" "ハッシュされていない時にはインストールがフェイルするでしょう。" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr ".data ディレクトリ" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " @@ -14521,7 +14296,7 @@ msgstr "" "dist-info ディレクトリと同様に命名されるが .data/ 拡張子をつけられて .data " "ディレクトリに行きます::" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " @@ -14531,11 +14306,11 @@ msgstr "" "ディレクトリに収めています。インストール中に、これらのサブディレクトリの内容" "を行き先となるパスへ動かします。" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "署名済み wheel ファイル" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -14552,7 +14327,7 @@ msgstr "" "れていますが、 RECORD は自身のハッシュ値を含むことができないので例外です。例" "えば::" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -14564,23 +14339,29 @@ msgstr "" "ん。アーカイブの中の他のファイルはすべて、RECORD ファイル内に正しいハッシュ値" "を持たなければならず、そうでなければインストールに失敗します。" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 +#, fuzzy +#| msgid "" +#| "If JSON web signatures are used, one or more JSON Web Signature JSON " +#| "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent " +#| "to RECORD. JWS is used to sign RECORD by including the SHA-256 hash of " +#| "RECORD as the signature's JSON payload::" msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" "JSON ウェブ署名が使われる場合には、ひとつかそれ以上の JSON Web Signature " "JSON Serialization (JWS-JS) 署名が RECORD ファイルの隣にある RECORD.jws ファ" "イルの中に保存されます。 RECORD ファイルの SHA-256 ハッシュ値を署名の JSON ペ" "イロードに含むことで RECORD ファイルに署名するために JWS が使われます::" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "(ハッシュ値の書き方のフォーマットは RECORD で使われるものと同じです。)" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." @@ -14588,7 +14369,7 @@ msgstr "" "RECORD.p7s を使う場合は、このファイルに RECORD ファイルに関する分離型の S/" "MIME 署名を入れておかなければなりません。" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -14601,15 +14382,15 @@ msgstr "" "確認する際には、別途用意された署名検証プログラムは RECORD ファイルが署名に対" "して妥当であることだけを確認すれば十分です。" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "以下を参照のこと" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "https://datatracker.ietf.org/doc/html/rfc7515" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" @@ -14617,94 +14398,28 @@ msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "https://datatracker.ietf.org/doc/html/rfc7517" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr ".egg との比較" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" -"Wheel はインストールするためのフォーマットのひとつですが、 egg はインポートす" -"ることができます。 Wheel アーカイブには .pyc が含まれている必要がないので、 " -"Python の特定のバージョンや実装に紐づく度合いがより小さくなります。 Wheel " -"は、以前のバージョンの Python でビルドされた (純 Python の) パッケージをイン" -"ストールすることができるので、必ずしもパッケージ制作者が追いつくのを待つ必要" -"がありません。" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" -"Wheel は .dist-info ディレクトリを使用するが、 egg は .egg-info を使います。 " -"Wheel は、 Python のパッケージングにおける新しい世界とそれがもたらす新しい概" -"念に適合しています。" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" -"Wheel は、今日の複数実装世界に合わせて、より表現力が高いファイル命名慣習を" -"持っています。単独の wheel アーカイブ (訳注、その名前) が、数々の Python 言語" -"のバージョンや実装、ABI やシステムアーキテクチャとの互換性を表示することがで" -"きるのです。歴史的には、 ABI は CPython のリリースに紐づいていましたが、 " -"wheel は安定な ABI に対応しています。" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" -"Wheel はロスレスです。最初の wheel 実装である bdist_wheel は常に egg-info を" -"生成し、それを .whl ファイルへ変換します。既存の egg ファイルを " -"bdist_wininst 配布物に変換することも可能です。" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" -"Wheel はバージョン付けされています。各 wheel ファイルは wheel 仕様およびパッ" -"ケージングに使われた実装のバージョンを含んでいます。次のマイグレーションが単" -"純に Wheel 2.0 へのものになれば良いのですが。" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "Wheel は、他の Python に対して参照するべきものとなっています。" - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "FAQ" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" "Wheel は .data ディレクトリを定義します。すべてのデータをそこに入れるべきで" "しょうか？" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -14720,11 +14435,11 @@ msgstr "" "*wheel の* ``.data`` ディレクトリに置く形で配布されない時でさえも、 " "``pkgutil.get_data(package, resource)`` を使い続けても構わないのです。" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "なぜ wheel は添付された署名を持つのか？" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -14737,11 +14452,11 @@ msgstr "" "も署名が無効にならず、また、アーカイブ全体をダウンロードしなくても個々のファ" "イルの検証を行うことができます。" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "なぜ wheel は JWS 署名を許容するのか？" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " @@ -14751,11 +14466,11 @@ msgstr "" "その性質は wheel の基本的な設計目標のひとつでもあります。 JWS は使いやすくて" "簡潔な純 Python の実装をもたらします。" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "なぜ wheel は S/MIME 署名をも許容するのか？" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." @@ -14763,7 +14478,7 @@ msgstr "" "S/MIME 署名は、既存の公開鍵基盤を wheel でも採用する必要があるか、または、採" "用したいユーザのために許容されています。" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." @@ -14772,11 +14487,11 @@ msgstr "" "ルディングブロックであるというだけのものです。 Wheel としては、単にビルディン" "グブロックを提供するだけです。" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "\"pure lib\" と \"plat lib\" って、どう扱えばいいの？" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -14789,7 +14504,7 @@ msgstr "" "ムに依存しないパッケージを '/usr/lib64/pythonX.Y/site-packages' にインストー" "ルします。" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -14802,7 +14517,7 @@ msgstr "" "ルと相同であり、 \"purelib\" と \"platlib\" の両カテゴリにファイル群が存在す" "ることには問題がありません。" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " @@ -14812,13 +14527,13 @@ msgstr "" "\"purelib\" または \"platlib\" のいずれか一方しか持たず、 \"Root-Is-" "purelib\" を適切に設定しつつファイル群をルートディレクトリに置くべきです。" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" "Python のソースコードを wheel ファイルから直接にインポートすることはできます" "か？" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -14832,7 +14547,7 @@ msgstr "" "す* 。しかし、このような動作はフォーマット設計の自然な結果とはいうものの、実" "際にはこれに依存することは一般的には推奨されていません。" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -14850,7 +14565,7 @@ msgstr "" "を適切な場所に公開することによって C 言語拡張をビルドする標準的な機構を完全に" "統合する機能) への信頼を故意に避けることになります。" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -14883,7 +14598,7 @@ msgstr "" "イスは依然として実際にディスク上に存在するファイルがないと動作できないかもし" "れません。" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -14898,52 +14613,53 @@ msgstr "" "バグであると認めてもらう前に、多くのプロジェクトではそれを完全インストールの" "状態で再現するように要求されるであろうということを認識しておいてください。" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" -msgstr "変更点" - -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" -msgstr ":pep:`427` 以来、この仕様には次のような修正が加えられました:" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "歴史" -#: ../source/specifications/binary-distribution-format.rst:477 -msgid "" -"The rules on escaping in wheel filenames were revised, to bring them into " -"line with what popular tools actually do (February 2021)." +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -"他の普及しているツールが実際にやるのと同じやり方に合わせて、 wheel のファイル" -"名におけるエスケーピングの規則が修正されました。" -#: ../source/specifications/binary-distribution-format.rst:484 +#: ../source/specifications/binary-distribution-format.rst:423 +#, fuzzy +#| msgid "" +#| "The following changes were made based on feedback after its initial " +#| "implementation:" +msgid "The following changes were applied since the initial version:" +msgstr "" +"以降の変更は、最初の実装 (ができた) 後に寄せられたフィードバックに基づくもの" +"です:" + +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" +"The rules on escaping in wheel filenames were revised, to bring them into " +"line with what popular tools actually do (February 2021)." msgstr "" -"PEP 受諾 (https://mail.python.org/pipermail/python-dev/2013-February/124103." -"html)" +"他の普及しているツールが実際にやるのと同じやり方に合わせて、 wheel のファイル" +"名におけるエスケーピングの規則が修正されました。" -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "補遺" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "urlsafe-base64-nopad の実装の例::" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "著作権" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "この文書はパブリックドメインに位置付けられる。" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "コアとなるメタデータの仕様" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" @@ -14951,23 +14667,23 @@ msgstr "" "この後の仕様の中で定義されるフィールドは、正当かつ完全であって、変更の可能性" "がないものと見做されるべきです。必須のフィールドは以下の通り:" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "``Name``" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "これら以外のすべてのフィールドは必須のものではありません。" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects ` before comparing." @@ -15121,15 +14831,12 @@ msgstr "" "比較の目的のためにも、名前は比較の前に :ref:`正規化 ` さ" "れているべきです。" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 #, fuzzy -#| msgid "" -#| "A string containing the distribution's version number. This field must " -#| "be in the format specified in :pep:`440`." msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " @@ -15138,11 +14845,11 @@ msgstr "" "配布物のバージョン番号を格納する文字列。このフィールドは :pep:`440` で規定さ" "れるフォーマットでなければなりません。" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "Dyanamic (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " @@ -15152,14 +14859,14 @@ msgstr "" "``Name`` ・ ``Version`` ・ ``Metadata-Version`` をこのフィールドに指定しては" "なりません。" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" "ソースコード配布物のメタデータ中に見つかった場合には、以下の規則を適用します:" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -15171,7 +14878,7 @@ msgstr "" "なりません。そのフィールドが sdist には存在せず、かつ、 ``Dynamic`` とマーク" "されていない場合には、そのようなフィールドは wheel に出現してはなりません。" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." @@ -15179,7 +14886,7 @@ msgstr "" "フィールドが ``Dynamic`` とマークされている場合、 (ひとつも存在しない場合も含" "めて) sdist からビルドされた wheel 内のどんな正当な値を取っても構いません。" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " @@ -15190,7 +14897,7 @@ msgstr "" "らビルドされた wheel のメタデータに何も特別な制約がないかのように) 取り扱うべ" "きです。" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -15201,16 +14908,16 @@ msgstr "" "り、そのフィールドの値がビルドの際に計算されたものであって、 sdist や同じプロ" "ジェクトでも他の wheel ファイルでは異なる場合があることを示します。" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "``Dynamic`` の詳細かつ完全な意味は :pep:`643` に記述されています。" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "Platform (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " @@ -15220,11 +14927,23 @@ msgstr "" "もので、 \"Operating System\" Trove 分類子には記載されていないもの。後述の " "\"分類子 \" を見てください。" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "例::" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "Supported-Platform (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -15236,19 +14955,19 @@ msgstr "" "ルされたかを指定することになるでしょう。 Supported-Platform フィールドのセマ" "ンティクスは PEP には定義されたものがありません。" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "Summary" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "その配布物が何をするものかを１行で記述した要約。" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "このフィールドの代わりにメッセージ本体で指定しても構いません。" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -15259,7 +14978,7 @@ msgstr "" "書並みの記述をするべきではありませんが、メタデータを扱うソフトウェアはこの" "フィールドに最大長さがあるものと仮定すべきではありません。" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -15272,7 +14991,7 @@ msgstr "" "示することも可能です。つまり、作者の側は、自分が採用するマークアップ言語につ" "いては保守的であるべきだということになります。" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -15284,7 +15003,7 @@ msgstr "" "りません。その結果として、Description フィールドが RFC 822 構文解析器 [2]_ で" "解析可能な形の改行可能なフィールドにエンコードされます。" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " @@ -15294,7 +15013,7 @@ msgstr "" "み取り器で読み取る時には、CRLF と７個の空白文字とそれに引き続くパイプ文字が出" "現するたびにそれを単独の CRLF に置き換えなければならないということです。" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " @@ -15304,11 +15023,11 @@ msgstr "" "下げやその他の特別なフォーマットを使わずに、ヘッダの並びの後の完全な空行に続" "けて書く) こともできます。" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "Description-Content-Type" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." @@ -15316,7 +15035,7 @@ msgstr "" "配布物の説明で使われるマークアップ構文 (もしあれば) を述べる文字列で、ツール" "の側が頭の良いやり方で説明を表示することができます。" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" msgstr ":rfc:`Github 流の Markdown <7764#section-3.2>` を指定する ``GFM``" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr ":rfc:`CommonMark <7764#section-3.5>` を指定する ``CommonMark``" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " @@ -15420,7 +15138,7 @@ msgstr "" "ては、まず ``text/x-rst; charset=UTF-8`` として表示を試み、正当な rst ではな" "い場合に ``text/plain`` にフォールバックするべきです。" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " @@ -15430,7 +15148,7 @@ msgstr "" "``text/plain`` であるものと仮定します (とはいえ、認識できない値であれば何で" "あっても PyPI が拒否することになるでしょう) 。" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " @@ -15440,7 +15158,7 @@ msgstr "" "ない場合や認識できない値が指定された場合には、 ``variant`` が ``GFM`` である" "ものと仮定されます。" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " @@ -15450,11 +15168,11 @@ msgstr "" "``variant`` はデフォルトでは ``GFM`` ですので、それ以前の例と同等であるという" "ことになります。" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "キーワード" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." @@ -15462,7 +15180,7 @@ msgstr "" "より大きなカタログで配布物を検索する助けとなるべく使用される、コンマで区切ら" "れた追加のキーワードのリスト。" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -15474,19 +15192,19 @@ msgstr "" "常に広く使われていますので、仕様をデファクト標準に合わせる形で更新する方が簡" "単でした。" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "Home-page" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "配布物のホームページを示す URL を含んだ文字列。" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "Download-URL" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" @@ -15497,22 +15215,22 @@ msgstr "" "うなものでは駄目で、 \".../BeagleVote-0.45.tgz\" のようにバージョンを含むもの" "でなければならないということです。)" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "Author" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" "少なくとも作者の名前を含む文字列で、連絡先となる情報を追加しても構いません。" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "Author-email" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." @@ -15520,8 +15238,8 @@ msgstr "" "作者の電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述形式" "として正当な形で名前と電子メールアドレスを含んでいても構いません。" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" @@ -15529,11 +15247,11 @@ msgstr "" "RFC-822 によれば、このフィールドは、複数の電子メールアドレスをコンマで区切っ" "て記述しても構いません::" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "メンテナ" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." @@ -15541,7 +15259,7 @@ msgstr "" "少なくともメンテナの名前を含む文字列で、連絡先となる情報を追加しても構いませ" "ん。" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " @@ -15551,11 +15269,11 @@ msgstr "" "フィールドを使うことを想定しているということを覚えておいてください: もし " "``Author`` と同一人物であれば、このフィールドを省略するべきです。" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "Maintainer-email" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." @@ -15563,7 +15281,7 @@ msgstr "" "メンテナの電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述" "形式として正当な形で名前と電子メールアドレスを含んでいても構いません。" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " @@ -15573,11 +15291,11 @@ msgstr "" "フィールドを使うことを想定しているということを覚えておいてください: もし " "``Author-email`` と同一であれば、このフィールドを省略するべきです。" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "License" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -15592,11 +15310,11 @@ msgstr "" "由して名指しされたライセンスの特定のバージョンを指定したり、そのようなライセ" "ンスに対する変種や例外事項を示したりするのに使っても構いません。" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "Classifier (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -15608,21 +15326,21 @@ msgstr "" "されている分類子 `__ という動的なリストを公開" "しています。" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "このフィールドでは、セミコロンの後に環境指標を続けても構いません。" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "Requires-Dist (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." @@ -15630,7 +15348,7 @@ msgstr "" "フィールドの仕様は、人気のある公開ツール群が用いる構文を許容するように緩めら" "れました。" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." @@ -15638,11 +15356,11 @@ msgstr "" "それぞれのエントリは、この配布物が要求する他の distutils のプロジェクトを名指" "しする文字列を含みます。" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "要求事項を示す文字列のフォーマットは、１個から４個の部分を含みます:" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." @@ -15650,7 +15368,7 @@ msgstr "" "``Name:`` フィールドと同じフォーマットのプロジェクト名。これだけが必須部分で" "す。" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -15662,7 +15380,7 @@ msgstr "" "``Provides-Extra:`` フィールドで指定された制約事項に従うものでなければなりま" "せん。" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." @@ -15670,7 +15388,7 @@ msgstr "" "バージョン指定子。この部分をパースするツールはバージョンを囲む括弧を許容しな" "ければならないが、生成する際には括弧を使ってはなりません。" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." @@ -15678,11 +15396,11 @@ msgstr "" "セミコロンの後ろに環境マーカ。要求事項が必要となるのが指定された条件の時のみ" "であることを示します。" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "許容されるフォーマットの詳細については :pep:`508` を見てください。" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." @@ -15690,7 +15408,7 @@ msgstr "" "プロジェクト名は、 `Python パッケージインデックス `_ に" "出現する名前に対応していなければなりません。" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." @@ -15698,16 +15416,12 @@ msgstr "" "バージョン指定子は :doc:`version-specifiers` に記述された規則に従っていなけれ" "ばなりません。" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 #, fuzzy -#| msgid "" -#| "This field specifies the Python version(s) that the distribution is " -#| "guaranteed to be compatible with. Installation tools may look at this " -#| "when picking which version of a project to install." msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " @@ -15717,27 +15431,27 @@ msgstr "" "を指定します。インストールツールは、プロジェクトのインストールするべきバー" "ジョンを選択する時にこのフィールドを参照しても構いません。" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" "値は、 :doc:`version-specifiers` で指定されたフォーマットでなければなりませ" "ん。" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "このフィールドでは、環境マーカを後ろに付けることはできません。" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "Requires-External (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -15749,7 +15463,7 @@ msgstr "" "担当者向けにヒントを提供することを意図しており、 ``distutils`` 配布物にとって" "は何ら意味を持ちません。" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." @@ -15757,13 +15471,8 @@ msgstr "" "要求事項の文字列のフォーマットは外部の依存先の名前で、必須ではありませんが括" "弧に入れたバージョンの宣言を後ろにつけても構いません。" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 #, fuzzy -#| msgid "" -#| "Because they refer to non-Python software releases, version numbers for " -#| "this field are **not** required to conform to the format specified in :" -#| "pep:`440`: they should correspond to the version scheme used by the " -#| "external dependency." msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -15774,30 +15483,30 @@ msgstr "" "バージョン番号は :pep:`440` で指定されたフォーマットに適合することを **要求さ" "れていません** 。" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "使用される文字列に対して特に規則がないという点に注意してください。" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "Project-URL (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" "そのプロジェクトの閲覧可能な URL とラベルを含む文字列をコンマで区切ったもの。" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "このラベルは32 文字以内のフリーテキストです。" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "Provides-Extra (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " @@ -15807,7 +15516,7 @@ msgstr "" "れた正当な値を。古めのメタデータのバージョンでは、 ``Name:`` を伴う行で値に制" "限が導入され、正規化規則も導入されました。" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -15820,7 +15529,7 @@ msgstr "" "フンは連続してはいけません。名前は次の正規表現にマッチしなければなりません " "(そうすることで曖昧さを排除します)::" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." @@ -15828,7 +15537,7 @@ msgstr "" "指定された名前は、追加的な機能が要求されたか否かに応じて依存関係を構築するた" "めに使われます。" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -15839,7 +15548,7 @@ msgstr "" "切ることで複数の機能を要求することができます。要求事項は、要求されたそれぞれ" "の機能について評価され、配布物の要求する依存関係の組に追加されます。" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " @@ -15848,7 +15557,7 @@ msgstr "" "``test`` と ``doc`` という二つの名前は、順に自動化されたテストと説明文書の生" "成のために必要な依存先として予約されています。" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." @@ -15856,7 +15565,7 @@ msgstr "" "``Requires-Diet:`` のどこからも参照されていなくても、 ``Provides-Extra:`` を" "指定しても構いません。" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -15868,7 +15577,7 @@ msgstr "" "の ``Provides-Extra:`` エントリが正規化後に衝突する場合には、メタデータを書き" "込むツールはエラーを発生させなければなりません。" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -15884,11 +15593,11 @@ msgstr "" "古めのメタデータバージョンとして不当な名前を読み取った場合には、ツールはエ" "ラーを発出することを選択しても構いません。" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "稀に使われるフィールド" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -15900,7 +15609,7 @@ msgstr "" "クスサーバの文脈でツールがどのように翻案するべきかが全く明らかではないので、" "現在ではほとんど使われません。" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -15916,11 +15625,11 @@ msgstr "" "トリと組み合わせれば本来意図された目的に用いることができることから、メタデー" "タの仕様には残されています。" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "Provides-Dist (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " @@ -15930,7 +15639,7 @@ msgstr "" "文字列で含みます。このフィールドは、プロジェクトを特定する ``Name`` フィール" "ドと後続するバージョンを *含んでいなければなりません*: Name (Version) 。" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -15944,7 +15653,7 @@ msgstr "" "の配布物として利用可能です。そのようなソースコード配布物をインストールする" "と、 ``ZODB`` と ``transaction`` の両方の要求事項を満たします。" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -15962,7 +15671,7 @@ msgstr "" "にはそのうちの高々１個だけがインストールされていれば十分な ``ORM-bindings`` " "を提供すると宣言していても構わないのです。" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " @@ -15972,11 +15681,11 @@ msgstr "" "specifiers>` に記述された規則に従ったものでなければなりません。もし指定されて" "いなければ、配布物のバージョン番号が暗黙理に使われます。" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "Obsoletes-Dist (複数回の使用可)" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " @@ -15986,7 +15695,7 @@ msgstr "" "プロジェクトが同時にインストールされるべきではない distutils プロジェクトの配" "布物を記述する文字列を含みます。" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." @@ -15994,7 +15703,7 @@ msgstr "" "バージョンの宣言があっても構いません。バージョン番号は :doc:`バージョン指定" "子 ` で指定されたフォーマットでなければなりません。" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " @@ -16005,19 +15714,19 @@ msgstr "" "しょう。 Torqued Python をインストールするなら、 Gorgon 配布物は削除されるべ" "きです。" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "非推奨となったフィールド" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "要求事項" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "``Requires-Dist`` に従って" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." @@ -16025,7 +15734,7 @@ msgstr "" "それぞれのエントリは、このパッケージが必要とする他のモジュールやパッケージを" "記述した文字列を含みます。" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " @@ -16035,7 +15744,7 @@ msgstr "" "るモジュールやパッケージの名前のフォーマットと同一のもので、オプションとして" "カッコ内に入れたバージョン宣言を伴うことがあります。" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -16052,7 +15761,7 @@ msgstr "" "ドットで区切ったものです。バージョン番号の例としては、 \"1.0\" や \"2.3a2\" " "や \"1.3.99\" 、" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." @@ -16060,7 +15769,7 @@ msgstr "" "例えば \">1.0, !=1.3.4, <2.0\" という文字列が正当なバージョン宣言であるよう" "に、比較演算子はいくつでも指定することができます。" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." @@ -16068,7 +15777,7 @@ msgstr "" "次に示すすべての要求仕様文字列 は実際に可能なものです: " "\"rfc822\", \"zlib (>=1.1.4)\", \"zope\"。" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." @@ -16077,15 +15786,15 @@ msgstr "" "ありません; 独自の標準を選択することが Python コミュニティに委ねられていま" "す。" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "提供する" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "``Provides-Dist`` を支持して " -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -16099,15 +15808,15 @@ msgstr "" "子なしなら) バージョン宣言もあっても構いません; もしバージョン宣言がなけれ" "ば、そのパッケージのバージョン番号を援用します。" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "古くなった " -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "``Obsoletes-Dist`` に従って" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " @@ -16118,7 +15827,7 @@ msgstr "" "これら二つのパッケージは同時にはインストールされるべきではないことを示す、そ" "のような文字列が含まれます。バージョン宣言を書いておくことができます。" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " @@ -16129,4184 +15838,4114 @@ msgstr "" "しょう。 Torqued Python をインストールするなら、 Gorgon パッケージは削除され" "るべきです。" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "reStructuredText マークアップ言語: https://docutils.sourceforge.io/" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "RFC 822 長形式ヘッダフィールド: :rfc:`822#section-3.1.1`" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" -msgstr "ビルドシステムの依存関係を宣言する" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "依存関係指定子" -#: ../source/specifications/declaring-build-dependencies.rst:8 -#, fuzzy -#| msgid "" -#| "`pyproject.toml` is a build system independent file format defined in :" -#| "pep:`518` that projects may provide in order to declare any Python level " -#| "dependencies that must be installed in order to run the project's build " -#| "system successfully." +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" -"`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファイル" -"形式で、あるプロジェクトのビルドシステムが正常に動作するためにインストールさ" -"れていなければならない Python レベルの依存関係をすべて宣言するという目的のた" -"めにそのプロジェクトが提供するものです。" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" +"元々は :pep:`508` で指定されていた依存関係指定子のフォーマットを、この説明文" +"書は記述します。" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" +"依存関係 の任務は、 pip [#pip]_ のようなツールがインストールする" +"べき正しいパッケージを探し出すことができるようにすることです。これは時には大" +"変に曖昧で名称を指定するだけであったり、別の時には非常に限定的でインストール" +"するべき特定のファイルを参照したりします。場合によっては、依存関係 " +" がひとつのプラットフォームでのみ妥当であったり、いくつかのバー" +"ジョンだけが受け入れ可能であったりするので、(依存関係 を記述す" +"る) 言語としてはこれらすべてのケースを記述できるものでなければなりません。" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 +#, fuzzy msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" +"定義された言語は、簡潔な行単位のフォーマットであって pip の requirements ファ" +"イルで既に広く使われているものですが、そのようなファイル群を書けるようなコマ" +"ンドラインオプションを指定することはしていません。ひとつ注意しなければならな" +"いのは、 :pep:`440` で指定されているような URL を参照するやり方は実は pip で" +"は実装されていないのに、 :pep:`440` が受け入れられている現状を鑑みて、今の " +"pip の本来のフォーマットよりもむしろそちらのフォーマットを使っているという点" +"です。" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "仕様" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" +msgstr "この言語のすべての機能を、名前に基づいた参照とともに示します::" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" +msgstr "最低限の URL に基づいた参照::" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "概念" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" +"依存関係の指定では、常に、配布物の名前を指定します。名前で指定された配布物で" +"特定の追加機能を有効にするように依存関係を拡張するような追加物 を含ん" +"でいても構いません。インストールされたバージョンをバージョンリミットで制御す" +"ることもできますし、特定のアーティファクトをインストールするために URL を与え" +"ることもできます。依存関係は最終的に環境マーカを用いて条件別に作成することも" +"できます。" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "文法" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" +"最初に文法について簡単に触れた後、それぞれの節の意味論 について深" +"く掘り下げることにしましょう。" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" -msgstr "プロジェクトのメタデータを宣言する" - -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -":pep:`621` では、パッケージング関連のツールが使用するために、あるプロジェクト" -"の :ref:`コアとなるメタデータ ` を ``pyproject.toml`` ファイル" -"にどのように書けば良いかを指定しています。使われるファイルフォーマットの基準" -"となる仕様として、以下のようなものを定義しています。" +"配布物の仕様は ASCII テキストで書かれています。厳密な文法としては parsley " +"[#parsley]_ の文法を使っています。この仕様は、コメントや継続による複数行サ" +"ポートやその他の機能の枠組みを与えるもっと大きなシステムの中に組み込まれるこ" +"とを期待しています。" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" +"役に立つ構文解析ツリーを構成するための注釈機能を含む完全な文法は、この説明文" +"書の末尾に置きました。" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "仕様" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 +#, fuzzy msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -"メタデータにはふたつの種類があります: *静的* なものと *動的* なものです。静的" -"なメタデータは ``pyproject.toml`` ファイルで直接指定されていて、ツール側では" -"指定したり変更したりできません (これは、例えばメタデータが参照するファイルの" -"内容のような、メタデータによって *参照* されるデータを含みます)。動的なメタ" -"データは ``dynamic`` キー (この仕様内で後で定義します) を経由して一覧化されて" -"いて、ツール側が後から提供することになるでしょう。" - -#: ../source/specifications/declaring-project-metadata.rst:30 -#, fuzzy -#| msgid "" -#| "The keys defined in this specification MUST be in a table named " -#| "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -#| "which are not defined by this specification. For tools wishing to store " -#| "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " -#| "table as defined in the :ref:`build dependency declaration specification " -#| "`. The lack of a ``[project]`` table " -#| "implicitly means the build back-end will dynamically provide all keys." -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" -"この仕様で定義されるキーは、 ``pyproject.toml`` ファイルの中の ``[project]`` " -"という名前のテーブルに収容されていなければなりません。いかなるツールもこの" -"テーブルにこの仕様で定義されていないキーを追加してはなりません。自身の設定を " -"``pyproject.toml`` ファイルに記録しておきたいと願うツールは、 :ref:`ビルド時" -"の依存関係を宣言するための仕様 ` で定義されてい" -"る通りに ``[tool]`` テーブルを使うことができます。 ``[project]`` テーブルが欠" -"落している場合は、ビルド用のバックエンドがすべてのキーを動的に提供するであろ" -"うということを暗黙理に意味しています。" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" -msgstr "必ず静的に定義しなければならない必須のキーは次の通り:" +":pep:`440` の規則に従ってバージョンを指定しても構いません。(ノート: URI は :" +"rfc:`std-66 <3986>` で定義されています)::" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -"必須フィールドだが、静的に指定しても動的に指定しても *いずれでも構わない* " -"キーは以下の通り:" +"環境マーカを使うことで、ある仕様が特定の環境でのみ有効であることを示すことが" +"できます::" -#: ../source/specifications/declaring-project-metadata.rst:48 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -"他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリ" -"ストしても未指定のままにしていても構いません。" +"配布物のうちの必須ではない部分については extras フィールドを使って指定するこ" +"とができます::" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" -msgstr "``[project]`` テーブルで許容されるキーの完全なリストは次のとおりです:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "追加物の名前に対する制限事項は :pep:`685` で定義されています。" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" -msgstr "``著者 ``" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" +msgstr "私たちに名前に基づいた要求仕様を与えてください::" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" -msgstr "``依存関係 " -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" -msgstr "``gui スクリプト ``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"行を分割するものではない空白文字には特に意味はなく、ほとんどの場合には必須で" +"はないものです。唯一の例外は、 URL による要求事項の末尾を検出するためのもので" +"す。" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" -msgstr "``保守者 ``" - -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" -msgstr "``optional-dependencies``" - -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "TOML_ 型: 文字列" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" +msgstr "名前 " -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`名前 " -"` フィールド" +"Python の配布物の名前は、現時点では :pep:`345` で定義されています。名前は配布" +"物の最も基本的な識別子として働きます。(名前は) あらゆる依存関係の指定に出現" +"し、それだけで十分に指定することができます。しかしながら、 PyPI では名前に厳" +"密な制約を課しています - 名前は大文字小文字を区別しない正規表現に合致しなけれ" +"ば受け入れられません。従って、この説明文書では、その正規表現に合致する識別子" +"だけを受け入れ可能な値として扱うことにしましょう。名前の完全な再定義はメタ" +"データ PEP として将来に出現するかもしれません。ここでいう (re.IGNORECASE とと" +"もに評価されるべき) 正規表現とは、次のようなものです::" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." -msgstr "プロジェクトの名前。" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" +msgstr "追加物 " -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -"内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を :ref:`" -"正規化 ` するべきです。" +"追加物とは、配布物の必須ではない部分のことです。配布物では追加物を幾つでも指" +"定することができ、追加物が依存関係の指定場所で使われた **場合** には、それぞ" +"れの追加物が配布物の追加的な依存関係を宣言する結果になります。例えば::" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -":ref:`コアとなるメタデータ ` に対応する: :ref:`バージョン " -"`" +"追加物 の依存関係の合併とは、その追加物が添付されている配布物 " +" の依存関係と一緒に定義されることです。上に示した例では、結果と" +"して requests がインストールされることになり、requests は自身の依存関係を持つ" +"ので requests の \"security\" 追加物 に列挙されたすべての依存関係 " +"(先) もインストールされることになります。" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" +"複数の追加物 が列挙されている場合には、すべての依存関係の合併集合が依" +"存関係になります。" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "ユーザは正規化済みのバージョンを指定するようにするべきです。" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" +msgstr "バージョン指定子" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:165 +#, fuzzy msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`要約 " -"`" - -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." -msgstr "プロジェクトを要約する記述。" +"バージョン番号やその比較方法について、詳しくは :pep:`440` をみてください。" +"バージョン仕様は、配布物のバージョンとして使うことができる範囲を定めていま" +"す。これは、名前によって参照される配布物にのみ適用されるのであって、URL を通" +"じて指定されるものには適用されません。バージョン番号の比較は、また、マーカー" +"機能においても使われます。バージョンの周囲にある必須でない括弧は :pep:`345` " +"との互換性を保つために存在していますが、そのようなものを生成すべきではなくて" +"受容するだけにとどめるべきです。" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" -msgstr "TOML_ 型: 文字列またはテーブル" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" +msgstr "環境マーカ" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -"対応する `コアとなるメタデータ ` フィールド: :ref:" -"`Description ` and :ref:`Description-Content-Type " -"`" - -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." -msgstr "プロジェクトの説明全体 (すなわち README)。" +"環境マーカは、依存関係の指定においてその依存関係がいつ使われるべきであるかを" +"記述する規則を提供します。例えば、あるパッケージが argparse を必要とするとし" +"ましょう。Python 2.7 では argparse は常に存在します。もっと古いバージョンの " +"Python では依存関係としてインストールされなければなりません。これは次のように" +"表現することができます::" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -"このキーは文字列かテーブルを受け付けます。もし文字列なら、完全な説明を含むテ" -"キストファイルの位置を ``pyproject.toml`` からの相対パスで示したものです。" -"ツールの側ではこのファイルが UTF-8 でエンコードされているものと想定しなければ" -"なりません。ファイルパスが大文字小文字を問わず ``.md`` 拡張子で終わっている場" -"合は、ツールはそのファイルの content-type が ``text/markdown`` であるものと仮" -"定しなければなりません。ファイルパスが大文字小文字を問わず ``.rst`` で終わっ" -"ている場合は、ツールは content-type が ``text/x-rst`` であるものと仮定しなけ" -"ればなりません。この PEP で指定するよりも多くの拡張子をツールが認識するなら、" -"そのようなツールは、このキーを ``dynamic`` であると指定していなくても、ユーザ" -"のために content-type を推測しても構いません。content-type が与えられていない" -"場合には、全ての認識できない拡張子についてツールはエラーを発生させなければな" -"りません。" +"マーカ表現は評価されると真か偽に帰着します。偽と評価された場合には、その依存" +"関係の指定は無視されなければなりません。" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -"``readme`` キーはその値がテーブルでも構いません。 ``file`` キーは、完全な説明" -"を含むファイルへの ``pyproject.toml`` ファイルからの相対パスを表現する文字列" -"を値として持ちます。 ``text`` キーは、完全な説明そのものである文字列を値に持" -"ちます。これらのキーは排他的にいずれかひとつしか使えないので、もしメタデータ" -"がこれら両方のキーを同時に指定していたらツールはエラーを発生させなければなり" -"ません。" +"マーカ言語は Python そのものに触発されたもので、セキュリティ上の脆弱性になり" +"かねない任意コードの実行を伴わずに安全に評価を行うことができるので選ばれまし" +"た。マーカは:pep:`345` で初めて標準化されました。この説明文書では、 :pep:" +"`426` に記述されたデザインに見られるいくつかの問題点を修正しています。" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:191 +#, fuzzy msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -"``readme`` キーに指定されたテーブルには、完全な説明の content-type を指定する" -"文字列を値とする ``content-type`` キーも含まれています。メタデータがこのキー" -"をテーブルの中で指定していない場合には、ツールはエラーを発生させなければなり" -"ません。メタデータで ``charset`` パラメータが指定されていない場合には、 " -"UTF-8 であるものと想定されます。ツールは各ツールが独自に選択した他のエンコー" -"ディングをサポートしても構いません。 :ref:`コアとなるメタデータ ` によってサポートされている content-type に変換することができるので" -"あれば、ツールはそのような代替 content-type をサポートしても構いません。そう" -"でなければ、ツールはサポートしていない content-type に対してエラーを発生させ" -"なければなりません。" +"マーカ表現の比較は、比較の演算子によって分類されます。 の中に" +"入っていない 演算子は、 Python における文字列でのそれと同様に動作" +"します。 演算子は、定義されている場合 (つまり両側に正当はバー" +"ジョン指定子を伴う場合) には、 :pep:`440` のバージョン比較規則を採用していま" +"す。演算子の動作が :pep:`440` で定義されておらず、かつ、その演算子が Python " +"に存在する場合には、当該演算子は Python での動作にフォールバックします。そう" +"でない場合にはエラーを発生させるべきです。例えば、次の表現はエラーを発生させ" +"る結果となるでしょう::" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:" -"`Requires-Python `" - -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." -msgstr "プロジェクトが要求する Python のバージョン。" - -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" -msgstr "TOML_ 型: テーブル" +"ユーザ側から供給された定数は、常に ``'`` または ``\"`` なる引用記号を伴った文" +"字列として符号化されます。バックスラッシュによるエスケープは定義されていませ" +"んが、現存する実装ではサポートされているということを忘れないでください。この" +"仕様には (バックスラッシュエスケープは) 含まれていませんが、それは、複雑性を" +"増加させてしまうことと、現時点では目に見えるほどの必要性がないことが理由で" +"す。同様に、非 ASCII 文字のサポートも定義していません: 我々が参照するようなラ" +"ンタイムのすべての変数は、 ASCII 文字のみで構成されているものと期待されていま" +"す。" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`License `" +"\"os_name\" のようなマーカの文法内の変数は、 Python のランタイム内でルック" +"アップすることで値へと解決されます。 \"extra\" を例外として、すべての値は現在" +"のすべてのバージョンの Python で定義されています - もし値が定義されていなけれ" +"ば、それはマーカの実装のエラーです。" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -"テーブルには二つのキーのうちのいずれか一つを書くことができます。 ``file`` " -"キーは、 ``pyproject.toml`` からプロジェクトのライセンス情報を含むファイルへ" -"の相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディン" -"グが UTF-8 であるものと仮定しなければなりません。 ``text`` キーは、プロジェク" -"トのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排" -"他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエ" -"ラーを発生させなければなりません。" - -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" -msgstr "TOML_ 型: 文字列のキー・バリュー組を伴ったインラインテーブルの配列" +"未知の変数は、評価して真 か偽 となる比較の結果を返すのではな" +"く、エラーを生成しなければなりません。" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Author ` ・ :ref:`Author-email ` ・ :ref:`Maintainer ` ・ :ref:`Maintainer-" -"email `" +"特定の Python 実装で値を計算することができない変数は、バージョンについては " +"``0`` として、その他のすべての変数については空文字列として評価されるべきで" +"す。" -#: ../source/specifications/declaring-project-metadata.rst:181 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -"プロジェクトの \"作者\" であると考えられる人々ないし組織。正確な意味はさまざ" -"まに解釈可能です — 元々のまたは主要な作者でも構わないし、現在の保守者やパッ" -"ケージのオーナでも構いません。" +"\"extra\" 変数は、扱いが特別です。それは wheel ファイルにおいて、その wheel " +"の ``METADATA`` ファイル内の特定の追加物 にどの仕様を適用するべきであ" +"るかを知らせるために使われますが、 ``METADATA`` ファイルの様式が :pep:`426` " +"のドラフトバージョンに基づいているので、現時点ではその仕様が存在していないの" +"です。それにも関わらず、この特別な扱いが行われる場所ではない文脈においては、 " +"\"extra\" 変数はその他の未知の変数と同様にエラーに帰着するべきです。" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." -msgstr "" -"\"maintainers\" キーは \"authors\" キーに似ていて、その正確な意味はさまざまに" -"解釈可能です。" +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" +msgstr "マーカ " -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." -msgstr "" -"これらのキーは、 ``name`` と ``email`` のふたつのキーを伴ったテーブルの配列を" -"受け入れます。両方の値は文字列でなければなりません。 ``name`` の値は、電子" -"メールアドレスにおける正当な名前 (すなわち、 :rfc:`822` における電子メールア" -"ドレスのアドレス部分に前置できる名前なら何でも可) で、コンマを含まないもので" -"なければなりません。 ``email`` の値は、正当な電子メールアドレスでなければなり" -"ません。これらのキーは共に必須ではありませんが、少なくともいずれかのキーが" -"テーブル内で指定されていなければなりません。" +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" +msgstr "Python 同等物" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" -msgstr "" -"データを使って :ref:`コアとなるメタデータ ` に書き込むやり方は" -"次の通りです:" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" +msgstr "値の例" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." -msgstr "" -"``name`` だけが与えられた場合には、その値を :ref:`Author ` なり :ref:`Maintainer ` なりに書き込みま" -"す。" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" +msgstr "``OS の名称 ``" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." -msgstr "" -"``email`` だけの場合には、その値を :ref:`Author-email ` なり :ref:`Maintainer-email ` なりに" -"書き込みます。" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" +msgstr "``os.name``" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." -msgstr "" -"``email`` と ``name`` の両方が与えられた場合には、 ``{name} <{email}>`` の" -"フォーマットで :ref:`Author-email ` なり :ref:" -"`Maintainer-email ` なりに書き込みます。" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." -msgstr "複数の値がある場合はコンマで区切るべきです。" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "``sys_platform``" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" -msgstr "TOML_ 型: 文字列の配列" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" +msgstr "``sys.platform``" -#: ../source/specifications/declaring-project-metadata.rst:217 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Keywords ` field: :ref:`Classifier " -"`" -msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Classifier `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" +msgstr "``platform.machine()``" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." -msgstr "プロジェクトに適合する Trove 分類子。" +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" +msgstr "``x86_64``" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" -msgstr "TOML_ 型: 文字列のキー・バリューを伴うテーブル" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" -msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Project-URL `" +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" +msgstr "``platform.python_implementation()``" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." -msgstr "" -"URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になってい" -"るもの。" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" -msgstr "エントリポイント" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" +msgstr "``platform_release``" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" -msgstr "" -"TOML_ 型: table (``[project.scripts]`` ・ ``[project.gui-scripts]`` ・ " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" +msgstr "``platform.release()``" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" -msgstr ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." -msgstr "" -"みっつのテーブルがエントリポイントに関係しています。 ``[project.scripts]`` " -"テーブルは、 :ref:`エントリポイント仕様 ` の中の " -"``console_scripts`` グループに対応しています。テーブル内のキーはエントリポイ" -"ントの名前であり、値は参照されるオブジェクトです。" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" +msgstr "``platform_system``" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." -msgstr "" -"``[project.gui-scripts]`` テーブルは、 :ref:`エントリポイント仕様 ` の中の ``gui_scripts`` グループに対応します。そのフォーマットは " -"``[project.scripts]`` と同じです。" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" +msgstr "``platform.system()``" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." -msgstr "" -"``[project.entry-points]`` テーブルは、テーブルの集合体です。それぞれのサブ" -"テーブルの名前は、ひとつのエントリポイントグループです。キーと値の意味すると" -"ころは ``[project.scripts]`` と同じです。ユーザはネストしたサブテーブルを作っ" -"てはならず、代わりにエントリポイントグループを１段階の深さに保つようにしなけ" -"ればなりません。" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." -msgstr "" -"メタデータの中に ``[project.entry-points.console_scripts]`` もしくは " -"``[project.entry-points.gui_scripts]`` というテーブルが定義されている場合は、" -"それぞれ ``[project.scripts]`` や ``[project.gui-scripts]`` と混同してしまう" -"といけないので、ビルド時のバックエンドがエラーを発生させなければなりません。" +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "``platform_version``" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" -msgstr "" -"TOML_ 型: :pep:`508` の文字列 (``dependencies``) の配列、および、 :pep:`508` " -"の文字列 (``optional-dependencies``) の配列の値を伴ったテーブル" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" +msgstr "``platform.version()``" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" -"`Requires-Dist ` および :ref:`Provides-Extra " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." -msgstr "(必須ではない) プロジェクトの依存関係。" +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" +msgstr "``python_version``" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." -msgstr "" -"``dependencies`` には、文字列の配列が値であるようなキーです。それぞれの文字列" -"がそのプロジェクトの依存関係を表現していて、正当な :pep:`508` の文字列として" -"フォーマットされていなければなりません。それぞれの文字列は、 :ref:`Requires-" -"Dist ` エントリに直接にマップしています。" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" +msgstr "``platform.python_version()``" + +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" +msgstr "``sys.implementation.name``" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" +msgstr "下方の定義を見てください" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." -msgstr "" -"``optional-dependencies`` は、それぞれのキーが追加物で、その値が文字列の配列" -"であるようなテーブルです。文字列の配列は正当な :pep:`508` の文字列でなければ" -"なりません。キーは :ref:`Provides-Extra ` とし" -"てみた時に正当な値でなければなりません。従って、配列の中のそれぞれの値は、一" -"致する :ref:`Provides-Extra ` メタデータに対応" -"する :ref:`Requires-Dist ` のエントリになりま" -"す。" +"An error except when defined by the context interpreting the specification." +msgstr "仕様を通訳する文脈で定義された場合を除くエラー。" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" -msgstr "TOML_ 型: 文字列の配列" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" +msgstr "``test``" -#: ../source/specifications/declaring-project-metadata.rst:308 +#: ../source/specifications/dependency-specifiers.rst:277 +#, fuzzy +#| msgid "" +#| "The ``implementation_version`` marker variable is derived from ``sys." +#| "implementation.version``::" msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`ダイ" -"ナミック ` フィールド" +"マーカ変数の ``implementation_version`` は、 ``sys.implementation.version`` " +"から派生したものです ::" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -"この PEP に列挙されたキーのどれを意図的に指定しないままにすることで他のツール" -"が動的にそのようなメタデータを準備することができる/しようとするかを規定しま" -"す。後述するツールによる設定に比較して、どのメタデータが目的を持って未指定に" -"されていて未指定のままであることを期待されているのかについて明確に描き出しま" -"す。" +"この環境マーカの節は、当初は :pep:`508` を通して定義されましたが、 :pep:" +"`345` における環境マーカの節を置き換えます。" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" +msgstr "完全な文法" -#: ../source/specifications/declaring-project-metadata.rst:317 +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" +msgstr "完全な parsley 文法::" + +#: ../source/specifications/dependency-specifiers.rst:407 +#, fuzzy +#| msgid "A test program - if the grammar is in a string ``grammar``::" +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "テストプログラム - もし ``grammar`` 文字列内に文法があれば::" + +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" +msgstr "PEP 508 に対する変更の要旨" + +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -"ビルド用のバックエンドは、静的に指定されたメタデータ (つまり ``dynamic`` 内に" -"列挙されたキーではないメタデータ) を尊重しなければなりません。" +"以降の変更は、最初の実装 (ができた) 後に寄せられたフィードバックに基づくもの" +"です:" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -"メタデータで ``dynamic`` 内に ``name`` が指定されている場合には、ビルド用バッ" -"クエンドがエラーを発生させなければなりません。" +"``python_version`` の定義は、 Python の将来のバージョンが二桁のメジャーバー" +"ジョンやマイナーバージョンを持つ場合 (例えば 3.10) でもそれを収容できるよう" +"に、 ``platform.python_version()[:3]`` から ``'.'.join(platform." +"python_version_tuple()[:2])`` へと変更されました。 [#future_versions]_" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -":ref:`コアとなるメタデータ ` の仕様において、あるキーが \"必須" -"である\" ものとして挙げられている場合には、メタデータはそのキーを静的に指定す" -"るか、または、 ``dynamic`` 内に指定するかしなければなりません (どちらでもない" -"場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必" -"須のフィールドが ``[project]`` テーブルの中にどんな形でも存在していないという" -"ことは不可能であるべきです)。" +"Python のパッケージをインストールする際に推奨されるツールである pip (http://" +"pip.readthedocs.org/en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "parsley PEG ライブラリ。 (https://pypi.python.org/pypi/parsley/)" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -":ref:`コアとなるメタデータ ` の仕様で、あるキーを \"必須ではな" -"い\" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデー" -"タを提供するという期待が持てるのであればメタデータではそのキーを ``dynamic`` " -"の中に挙げても構いません。" +"Python の将来のバージョンでは、環境マーカ変数の ``python_version`` の定義が問" +"題をはらむかもしれません。 (https://github.com/python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "インストールされた配布物の配布元へ直接アクセスする URL を記録する" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/direct-url.rst:8 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -"メタデータ内で、あるキーが静的に指定されていて、かつ、 ``dynamic`` にも挙げて" -"ある場合には、ビルド用バックエンドはエラーを発生させなければなりません。" +"この説明文書では、インストール済みの配布物の `*.dist-info` ディレクトリにあ" +"る :file:`direct_url.json` ファイルによって配布物の配布元へ直接アクセスする " +"URL を記録する方法を指定します。 ``*.dist-info`` ディレクトリの一般的な構造と" +"使用方法は、 :ref:`インストール済みパッケージを記録する ` に記述されています。" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/direct-url.rst:17 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -"メタデータ内で、あるキーを ``dynamic`` の中に挙げなかった場合は、ビルド用バッ" -"クエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわ" -"ち、ツールがメタデータを挿入できるのは ``dynamic`` の中だけであり、かつ、ユー" -"ザがそうするようにオプトインしていなければならないということです) 。" +":file:`direct_url.json` ファイルは、要求事項が指定するダイレクト (VCS の URL " +"を含む) 参照 URL からインストールしている時に、インストーラによって :file:`*." +"dist-info` ディレクトリに生成されなければなりません。" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -"あるキーが ``dynamic`` の中で指定されたメタデータで、しかし、ビルド用バックエ" -"ンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエ" -"ンドはエラーを発生させなければなりません (正確な値であると判断した場合はデー" -"タを省略することが許容されます) 。" - -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" -msgstr "依存関係指定子" +"他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインス" +"トールする際には、このファイルを生成してはなりません。" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:24 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -"元々は :pep:`508` で指定されていた依存関係指定子のフォーマットを、この説明文" -"書は記述します。" +"この JSON ファイルは、 :rfc:`8259` に準拠するように UTF-8 で符号化されていな" +"ければならず、シリアル化の方法は :doc:`direct-url-data-structure` でなければ" +"なりません。" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:29 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -"依存関係 の任務は、 pip [#pip]_ のようなツールがインストールする" -"べき正しいパッケージを探し出すことができるようにすることです。これは時には大" -"変に曖昧で名称を指定するだけであったり、別の時には非常に限定的でインストール" -"するべき特定のファイルを参照したりします。場合によっては、依存関係 " -" がひとつのプラットフォームでのみ妥当であったり、いくつかのバー" -"ジョンだけが受け入れ可能であったりするので、(依存関係 を記述す" -"る) 言語としてはこれらすべてのケースを記述できるものでなければなりません。" +"要求された URL が file:// スキームであって VCS からチェックアウトしたものを含" +"むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情" +"報をも推定してはならず、従って、いかなる (``vcs_info`` のような) VCS 関連情報" +"をも :file:`direct_url.json` に出力してはなりません。" -#: ../source/specifications/dependency-specifiers.rst:16 -#, fuzzy -#| msgid "" -#| "The language defined is a compact line based format which is already in " -#| "widespread use in pip requirements files, though we do not specify the " -#| "command line option handling that those files permit. There is one caveat " -#| "- the URL reference form, specified in :pep:`440` is not actually " -#| "implemented in pip, but since :pep:`440` is accepted, we use that format " -#| "rather than pip's current native format." +#: ../source/specifications/direct-url.rst:36 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -"定義された言語は、簡潔な行単位のフォーマットであって pip の requirements ファ" -"イルで既に広く使われているものですが、そのようなファイル群を書けるようなコマ" -"ンドラインオプションを指定することはしていません。ひとつ注意しなければならな" -"いのは、 :pep:`440` で指定されているような URL を参照するやり方は実は pip で" -"は実装されていないのに、 :pep:`440` が受け入れられている現状を鑑みて、今の " -"pip の本来のフォーマットよりもむしろそちらのフォーマットを使っているという点" -"です。" - -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" -msgstr "この言語のすべての機能を、名前に基づいた参照とともに示します::" +"一般的な規則として、 :file:`direct_url.json` を生成する際には、インストーラは" +"可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 user:" +"password を環境変数から読み込むなら環境変数を参照するような URL として保存さ" +"れるべきであり、 ``requested_revision`` は要求された URL の中に出現するものを" +"極力そのまま反映するべきです。しかしながら、この情報は (``commit_id`` のよう" +"な) もっと精密なデータを使って *精製* されます。" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" -msgstr "最低限の URL に基づいた参照::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "pip コマンドの例と direct_url.json に与える影響" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" -msgstr "概念" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "``direct_url.json`` を生成するコマンド:" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -"依存関係の指定では、常に、配布物の名前を指定します。名前で指定された配布物で" -"特定の追加機能を有効にするように依存関係を拡張するような追加物 を含ん" -"でいても構いません。インストールされたバージョンをバージョンリミットで制御す" -"ることもできますし、特定のアーティファクトをインストールするために URL を与え" -"ることもできます。依存関係は最終的に環境マーカを用いて条件別に作成することも" -"できます。" - -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" -msgstr "文法" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -"最初に文法について簡単に触れた後、それぞれの節の意味論 について深" -"く掘り下げることにしましょう。" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -"配布物の仕様は ASCII テキストで書かれています。厳密な文法としては parsley " -"[#parsley]_ の文法を使っています。この仕様は、コメントや継続による複数行サ" -"ポートやその他の機能の枠組みを与えるもっと大きなシステムの中に組み込まれるこ" -"とを期待しています。" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -"役に立つ構文解析ツリーを構成するための注釈機能を含む完全な文法は、この説明文" -"書の末尾に置きました。" -#: ../source/specifications/dependency-specifiers.rst:60 -#, fuzzy -#| msgid "" -#| "Versions may be specified according to the :pep:`440` rules. (Note: URI " -#| "is defined in :rfc:`std-66 <3986>`)::" -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -":pep:`440` の規則に従ってバージョンを指定しても構いません。(ノート: URI は :" -"rfc:`std-66 <3986>` で定義されています)::" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -"環境マーカを使うことで、ある仕様が特定の環境でのみ有効であることを示すことが" -"できます::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (この場合、 ``url`` は git リポジトリのクローン先" +"のローカルディレクトリになり、 ``dir_info`` は ``\"editable\": true`` という" +"形で存在し、 ``vcs_info`` は設定されないということになるでしょう)" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -"配布物のうちの必須ではない部分については extras フィールドを使って指定するこ" -"とができます::" - -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." -msgstr "追加物の名前に対する制限事項は :pep:`685` で定義されています。" - -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" -msgstr "私たちに名前に基づいた要求仕様を与えてください::" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" -msgstr "そして、直接参照に用いる要求仕様のための規則はこちら::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "``direct_url.json`` を *生成しない* コマンド" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" -msgstr "依存関係を指定することができる統一規則への案内はこちら::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" -msgstr "空白文字 " +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -"行を分割するものではない空白文字には特に意味はなく、ほとんどの場合には必須で" -"はないものです。唯一の例外は、 URL による要求事項の末尾を検出するためのもので" -"す。" +"2020年3月: ``direct_url.json`` メタデータファイルは、当初は :pep:`610` で仕様" +"を指定されていましたが、ここで正式に文書化されました。" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" -msgstr "名前 " +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "ダイレクト URL データ構造 " -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -"Python の配布物の名前は、現時点では :pep:`345` で定義されています。名前は配布" -"物の最も基本的な識別子として働きます。(名前は) あらゆる依存関係の指定に出現" -"し、それだけで十分に指定することができます。しかしながら、 PyPI では名前に厳" -"密な制約を課しています - 名前は大文字小文字を区別しない正規表現に合致しなけれ" -"ば受け入れられません。従って、この説明文書では、その正規表現に合致する識別子" -"だけを受け入れ可能な値として扱うことにしましょう。名前の完全な再定義はメタ" -"データ PEP として将来に出現するかもしれません。ここでいう (re.IGNORECASE とと" -"もに評価されるべき) 正規表現とは、次のようなものです::" - -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" -msgstr "追加物 " +"この説明文書では、python プロジェクトや VCS 上のソースツリーやローカルのソー" +"スツリーやソースコード配布物や wheel ファイルのような配布物アーティファクトに" +"対してURLを表現することを可能とする、 JSON のシリアル化抽象データ構造の仕様を" +"定義します。" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:13 +#, fuzzy msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -"追加物とは、配布物の必須ではない部分のことです。配布物では追加物を幾つでも指" -"定することができ、追加物が依存関係の指定場所で使われた **場合** には、それぞ" -"れの追加物が配布物の追加的な依存関係を宣言する結果になります。例えば::" +"この :roc:`1738` URL としてのデータ構造の部分の表現方法は、本所執筆時点では、" +"公式に指定されていません。よくある表現方法は pip での URL フォーマットです。" +"他の例が :pep:`440` で提供されています。" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -"追加物 の依存関係の合併とは、その追加物が添付されている配布物 " -" の依存関係と一緒に定義されることです。上に示した例では、結果と" -"して requests がインストールされることになり、requests は自身の依存関係を持つ" -"ので requests の \"security\" 追加物 に列挙されたすべての依存関係 " -"(先) もインストールされることになります。" +"直接 URL データ構造は辞書でなければならず、 :rfc:`8259` に従って JSON にシリ" +"アライズできなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -"複数の追加物 が列挙されている場合には、すべての依存関係の合併集合が依" -"存関係になります。" +"それは少なくともふたつのフィールドを含んでいなければなりません。第１のフィー" +"ルドは ``string`` 型の ``url`` です。 ``url`` が何を参照しているかによって、" +"第２のフィールドは、 (``url`` が VCS への参照であるなら) ``vcs_info`` である" +"か、 (``url`` がソースコードのアーカイブまたは wheel を参照しているなら) " +"``archive_info`` であるか、または、 (``url`` がローカルのディレクトリを参照し" +"ているなら) ``dir_info`` であるかのうちのひとつでなければなりません。これらの" +"情報フィールドは、 (空であることも可能ですが) 以下に定義するような取り得る" +"キーを持った下位の辞書を値に取ります。" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" -msgstr "バージョン指定子" +#: ../source/specifications/direct-url-data-structure.rst:31 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"固持する場合には、``url`` は、セキュリティ上の理由から、機微に関わる認証情報" +"をすべて削除しておかなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:34 #, fuzzy #| msgid "" -#| "See :pep:`440` for more detail on both version numbers and version " -#| "comparisons. Version specifications limit the versions of a distribution " -#| "that can be used. They only apply to distributions looked up by name, " -#| "rather than via a URL. Version comparison are also used in the markers " -#| "feature. The optional brackets around a version are present for " -#| "compatibility with :pep:`345` but should not be generated, only accepted." +#| "The user:password section of the URL MAY however be composed of " +#| "environment variables, matching the following regular expression::" msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -"バージョン番号やその比較方法について、詳しくは :pep:`440` をみてください。" -"バージョン仕様は、配布物のバージョンとして使うことができる範囲を定めていま" -"す。これは、名前によって参照される配布物にのみ適用されるのであって、URL を通" -"じて指定されるものには適用されません。バージョン番号の比較は、また、マーカー" -"機能においても使われます。バージョンの周囲にある必須でない括弧は :pep:`345` " -"との互換性を保つために存在していますが、そのようなものを生成すべきではなくて" -"受容するだけにとどめるべきです。" - -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" -msgstr "環境マーカ" +"しかしながら、次に述べる正規表現に合致する形で URL の user:password の部分を" +"環境変数から構成しても構いません::" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -"環境マーカは、依存関係の指定においてその依存関係がいつ使われるべきであるかを" -"記述する規則を提供します。例えば、あるパッケージが argparse を必要とするとし" -"ましょう。Python 2.7 では argparse は常に存在します。もっと古いバージョンの " -"Python では依存関係としてインストールされなければなりません。これは次のように" -"表現することができます::" +"さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない" +"文字列であっても構いません。典型的な例としては、 ``ssh://git@gitlab.com/user/" +"repo`` のような URL における ``git`` を挙げることができます。" -#: ../source/specifications/dependency-specifiers.rst:181 -msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." -msgstr "" -"マーカ表現は評価されると真か偽に帰着します。偽と評価された場合には、その依存" -"関係の指定は無視されなければなりません。" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" +msgstr "VCS URL群" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -"マーカ言語は Python そのものに触発されたもので、セキュリティ上の脆弱性になり" -"かねない任意コードの実行を伴わずに安全に評価を行うことができるので選ばれまし" -"た。マーカは:pep:`345` で初めて標準化されました。この説明文書では、 :pep:" -"`426` に記述されたデザインに見られるいくつかの問題点を修正しています。" +"``url`` が VCS リポジトリを参照している場合、 以下のキー群を伴った " +"``vcs_info`` キーが辞書に存在していなければなりません:" -#: ../source/specifications/dependency-specifiers.rst:189 -#, fuzzy -#| msgid "" -#| "Comparisons in marker expressions are typed by the comparison operator. " -#| "The operators that are not in perform the same " -#| "as they do for strings in Python. The operators use the :" -#| "pep:`440` version comparison rules when those are defined (that is when " -#| "both sides have a valid version specifier). If there is no defined :pep:" -#| "`440` behaviour and the operator exists in Python, then the operator " -#| "falls back to the Python behaviour. Otherwise an error should be raised. " -#| "e.g. the following will result in errors::" +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -"マーカ表現の比較は、比較の演算子によって分類されます。 の中に" -"入っていない 演算子は、 Python における文字列でのそれと同様に動作" -"します。 演算子は、定義されている場合 (つまり両側に正当はバー" -"ジョン指定子を伴う場合) には、 :pep:`440` のバージョン比較規則を採用していま" -"す。演算子の動作が :pep:`440` で定義されておらず、かつ、その演算子が Python " -"に存在する場合には、当該演算子は Python での動作にフォールバックします。そう" -"でない場合にはエラーを発生させるべきです。例えば、次の表現はエラーを発生させ" -"る結果となるでしょう::" +"(``git`` ・ ``hg`` ・ ``bzr`` ・ ``svn`` のいずれかのような) VCS の名前を含ん" +"だ ``vcs`` キー (``string`` 型) が存在していなければなりません。その他の VCS " +"については、この仕様を修正するための PEP を書くことによって登録されるべきで" +"す。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが " +"手を離してしまえるようにするために、 ``url`` の値は対応する VCS と齟齬のない" +"ものでなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -"ユーザ側から供給された定数は、常に ``'`` または ``\"`` なる引用記号を伴った文" -"字列として符号化されます。バックスラッシュによるエスケープは定義されていませ" -"んが、現存する実装ではサポートされているということを忘れないでください。この" -"仕様には (バックスラッシュエスケープは) 含まれていませんが、それは、複雑性を" -"増加させてしまうことと、現時点では目に見えるほどの必要性がないことが理由で" -"す。同様に、非 ASCII 文字のサポートも定義していません: 我々が参照するようなラ" -"ンタイムのすべての変数は、 ASCII 文字のみで構成されているものと期待されていま" -"す。" +"``requested_revision`` キー (``string`` 型) は、ブランチ・タグ・リファレン" +"ス・コミット・リビジョンその他を指定するために存在していても構いません (VCS " +"と互換性を持つフォーマットにて)。" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -"\"os_name\" のようなマーカの文法内の変数は、 Python のランタイム内でルック" -"アップすることで値へと解決されます。 \"extra\" を例外として、すべての値は現在" -"のすべてのバージョンの Python で定義されています - もし値が定義されていなけれ" -"ば、それはマーカの実装のエラーです。" +"``commit_id`` キー (``string`` 型) は、正確にどのコミットまたはリビジョンがイ" +"ンストールされた/されるかを示すもので、必須のキーです。 VCS がリビジョン識別" +"子に基づくコミットハッシュをサポートしているなら、インストールされたものの" +"ソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュを " +"``commit_id`` として使わなければなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" +msgstr "アーカイブ URL 群" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -"未知の変数は、評価して真 か偽 となる比較の結果を返すのではな" -"く、エラーを生成しなければなりません。" +"``url`` がソースコードのアーカイブや wheel ファイルを指し示す場合には、 " +"``archive_info`` キーが次のようなキーを持つ辞書の形で存在しなければなりませ" +"ん:" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -"特定の Python 実装で値を計算することができない変数は、バージョンについては " -"``0`` として、その他のすべての変数については空文字列として評価されるべきで" -"す。" +"``hashes`` キーは、ハッシュ名から16進数表記のファイルハッシュ値への対応を保持" +"する辞書として存在するべきです。" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -"\"extra\" 変数は、扱いが特別です。それは wheel ファイルにおいて、その wheel " -"の ``METADATA`` ファイル内の特定の追加物 にどの仕様を適用するべきであ" -"るかを知らせるために使われますが、 ``METADATA`` ファイルの様式が :pep:`426` " -"のドラフトバージョンに基づいているので、現時点ではその仕様が存在していないの" -"です。それにも関わらず、この特別な扱いが行われる場所ではない文脈においては、 " -"\"extra\" 変数はその他の未知の変数と同様にエラーに帰着するべきです。" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" -msgstr "マーカ " - -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" -msgstr "Python 同等物" +"複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何を" +"するか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何も" +"しなくても構いません) については利用する側次第です。" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" -msgstr "値の例" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "これらのハッシュの名前は、常に小文字に正規化されているべきです。" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" -msgstr "``OS の名称 ``" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." +msgstr "" +"``hash lib`` 経由で利用可能なハッシュアルゴリズム (とりわけ、 ``hashlib." +"new()`` に渡すことができて、かつ、追加的なパラメータを必要としないもの) はど" +"れでも、ハッシュ値を格納する辞書のキーとして用いることができます。 ``hashlib." +"algorithms_garanteed`` から安全なアルゴリズムを少なくともひとつ選択して (訳" +"注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点では、 ``sha256`` が特に" +"推奨されています。" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" -msgstr "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"非推奨となった ``hash`` キー (``string`` 型) は、後方互換性を保つ目的でなら " +"``=`` を値に取る形で存在していても構いません。" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" -msgstr "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" +"データ構造を生成する側では、ひとつまたは複数のハッシュが利用できるなら " +"``hashes`` キーを生成するべきです。以前からそうしていたので既存のクライアント" +"のために後方互換性を保つためなら、生成側は ``hash`` キーの生成を継続するべき" +"です。" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" -msgstr "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"``hash`` と ``hashes`` の両方のキーが存在する時は、 ``hash`` キーの中に現れる" +"ハッシュは、 ``hashes`` の辞書の中にも存在しなければならず、そうすることで利" +"用する側では ``hashes`` キーがあればそれだけを考慮し、なければ ``hash`` に" +"フォールバックすることが可能になります。" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" -msgstr "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" +msgstr "ローカルディレクトリ" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:102 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (\"linux\" は Python3 か" -"ら、\"linux2\" は Python2 からであることに注意してください)" +"``url`` がローカルのディレクトリを参照している場合には、以下のキーを含む辞書" +"として ``dir_info`` キーが存在していなければなりません。" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" -msgstr "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." +msgstr "" +"配布物が編集可能モードでインストールされた/される場合には ``editable`` " +"(``boolean`` 型): ``true`` 、そうでなければ ``false`` 。存在していない場合の" +"デフォルトは ``false`` です。" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" -msgstr "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"``url`` がローカルのディレクトリを参照している場合、 :rfc:``8089` に適合する " +"``file`` スキームが存在していなければなりません。特にパス部分は絶対パスでなけ" +"ればなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはその" +"まま保存されているべきです。" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" -msgstr "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" +msgstr "サブディレクトリ内のプロジェクト群" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" -msgstr "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +msgstr "" +"トップレベルの ``subdirectory`` フィールドは、 ``pyproject.toml`` または " +"``setup.py`` が存在する場所を指定するために、 VCS リポジトリやソースコードの" +"アーカイブやローカルのディレクトリのルートディレクトリに対する相対パスとして" +"示したディレクトリパスを値とするものとして存在することが許されています。" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" -msgstr "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" +msgstr "登録済みの VCS" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" -msgstr "``CPython``, ``Jython``" - -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" -msgstr "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"この節では登録済み VCS; ``vcs`` や ``requested_revision`` やその他の " +"``vcs_info`` 内のフィールドや、さらにある場合には特定の VCS に特有のフィール" +"ドなどの使い方のような拡張された VCS 特有の情報 の一覧を示します。 PEP を書く" +"ことでこの仕様を修正する形で別の VCS を登録することが推奨されていますが、ツー" +"ルの側で他の VCS を (訳注、VCS 登録作業抜きで) サポートしても構いません。 " +"``vcs`` フィールドの値は、 (小文字の) コマンド名であるべきです。当該 VCS をサ" +"ポートするのに必要であると思われるその他のフィールドについては、当該 VCS のコ" +"マンド名で始まる名前にするべきです。" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" -msgstr "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" +msgstr "Git" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" -msgstr "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" +msgstr "ホームページ" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" -msgstr "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" -msgstr "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" +msgstr "vcs コマンド" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" -msgstr "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" +msgstr "git" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" -msgstr "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" +msgstr "``vcs`` フィールド" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" -msgstr "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" +msgstr "``requested_revision`` フィールド" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:145 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その" +"他のコミットハッシュ的なもの。" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" -msgstr "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" +msgstr "``commit_id`` フィールド" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" -msgstr "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "コミットハッシュ (16進数で40文字のSHA1)。" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" -msgstr "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"ツールは、 ``requested_revision`` が Git 参照に対応しているか否かを判断するた" +"めに ``git show-ref`` や ``git symbolic-ref`` コマンドを使うことができます。" +"さらに、 ``refs/tags/`` で始まる参照はタグに対応し、クローンした後に ``refs/" +"remotes/origin/`` で始まる参照はブランチに対応します。" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" -msgstr "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" +msgstr "Mercurial" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" -msgstr "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" -msgstr "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "hg" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" -msgstr "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" -msgstr "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "チェンジセット ID (16 進数で 40 文字)。" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" -msgstr "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" +msgstr "Bazaar" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" -msgstr "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" -msgstr "下方の定義を見てください" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" +msgstr "bzr" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" -msgstr "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." +msgstr "タグ名・ブランチ名・リビジョン id 。" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." -msgstr "仕様を通訳する文脈で定義された場合を除くエラー。" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." +msgstr "リビジョン id 。" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" -msgstr "``test``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -"マーカ変数の ``implementation_version`` は、 ``sys.implementation.version`` " -"から派生したものです ::" +"``requested_revision`` は、 ``svn checkout`` ``--revision`` オプションと互換" +"でなければなりません。 Subversion では、ブランチまたはタグは ``url`` の一部で" +"す。" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -"この環境マーカの節は、当初は :pep:`508` を通して定義されましたが、 :pep:" -"`345` における環境マーカの節を置き換えます。" +"Subversion は大域的にユニークな識別子をサポートしていないので、このフィールド" +"は当該リポジトリにおける Subversion のリビジョン番号です。" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" -msgstr "完全な文法" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" +msgstr "ソースコードアーカイブ:" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" -msgstr "完全な parsley 文法::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" +msgstr "タグおよびコミットハッシュ付きの Git のURL:" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" -msgstr "テストプログラム - もし ``grammar`` 文字列内に文法があれば::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" +msgstr "ローカルディレクトリ:" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" -msgstr "PEP 508 に対する変更の要旨" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" +msgstr "編集可能モード状態にあるローカルディレクトリ:" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -"以降の変更は、最初の実装 (ができた) 後に寄せられたフィードバックに基づくもの" -"です:" +"2020年3月: このデータ構造は、当初は :pep:`610` で ``direct_url.json`` メタ" +"データファイルの一部として仕様を指定されていましたが、ここで正式に文書化され" +"ました。" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -"``python_version`` の定義は、 Python の将来のバージョンが二桁のメジャーバー" -"ジョンやマイナーバージョンを持つ場合 (例えば 3.10) でもそれを収容できるよう" -"に、 ``platform.python_version()[:3]`` から ``'.'.join(platform." -"python_version_tuple()[:2])`` へと変更されました。 [#future_versions]_" +"2023年1月: ``archive_info.hashes`` キーを追加しました ([議論] (https://" +"discuss.python.org/t/22299)) 。" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "エントリポイントの仕様" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:7 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -"Python のパッケージをインストールする際に推奨されるツールである pip (http://" -"pip.readthedocs.org/en/stable/)" - -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" -msgstr "parsley PEG ライブラリ。 (https://pypi.python.org/pypi/parsley/)" +"*エントリポイント* は、インストールされた配布物が他のプログラムから発見され使" +"用されるように提供するコンポーネントを広報するためのメカニズムです。例えば:" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -"Python の将来のバージョンでは、環境マーカ変数の ``python_version`` の定義が問" -"題をはらむかもしれません。 (https://github.com/python/peps/issues/560)" - -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" -msgstr "インストールされた配布物の配布元へ直接アクセスする URL を記録する" +"配布物では、それぞれが関数を参照するような ``console_scripts`` エントリポイン" +"トを指定することができます。 *pip* (または console_scripts を認識する他のイン" +"ストーラ) が配布物をインストールする際に、各エントリポイントのコマンドライン" +"ラッパを生成します。" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:14 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -"この説明文書では、インストール済みの配布物の `*.dist-info` ディレクトリにあ" -"る :file:`direct_url.json` ファイルによって配布物の配布元へ直接アクセスする " -"URL を記録する方法を指定します。 ``*.dist-info`` ディレクトリの一般的な構造と" -"使用方法は、 :ref:`インストール済みパッケージを記録する ` に記述されています。" +"アプリケーションは、プラグインをロードするためにエントリポイントを用いること" +"ができます; 例えば、 Pygments (シンタックスハイライトを行うツール) は追加的な" +"字句解析器を使うことが可能であり、また、別にインストールされたパッケージから" +"提供されるスタイルを使うことができます。この件の詳細については、 :doc:`/" +"guides/creating-and-discovering-plugins` を見てください。" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:19 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -":file:`direct_url.json` ファイルは、要求事項が指定するダイレクト (VCS の URL " -"を含む) 参照 URL からインストールしている時に、インストーラによって :file:`*." -"dist-info` ディレクトリに生成されなければなりません。" +"エントリポイントのファイルフォーマットは、元々は、 setuptools でビルドされた" +"パッケージが、動作時 (ランタイム) に ``importlib.metadata`` で読み取られるで" +"あろうと思われるインテグレーションポイントメタデータを提供できるようにと開発" +"されました。現在では、 setuptools 以外のビルドツールが ``importlib." +"metadata`` と互換性のあるエントリポイントのメタデータを公開し、 ``importlib." +"metadata`` 以外のランタイムライブラリが移植可能な形で公開されているエントリポ" +"イントのメタデータを (潜在的には、たとえ異なるキャッシングと衝突回避の戦略を" +"採用していたとしても) 読み取ることができるようにと PyPA 相互互換性仕様におい" +"て定義されています。" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." -msgstr "" -"他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインス" -"トールする際には、このファイルを生成してはなりません。" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "データモデル" -#: ../source/specifications/direct-url.rst:24 -msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -"この JSON ファイルは、 :rfc:`8259` に準拠するように UTF-8 で符号化されていな" -"ければならず、シリアル化の方法は :doc:`direct-url-data-structure` でなければ" -"なりません。" +"概念的に、エントリポイントは３個の属性を持たなければならないと定義されていま" +"す:" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:32 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -"要求された URL が file:// スキームであって VCS からチェックアウトしたものを含" -"むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情" -"報をも推定してはならず、従って、いかなる (``vcs_info`` のような) VCS 関連情報" -"をも :file:`direct_url.json` に出力してはなりません。" +"エントリポイントが属する *group* は、それがどのような種類のオブジェクトを提供" +"するのかを示します。例えば、 ``console_scripts`` グループはコマンドとして使え" +"る関数を参照するエントリポイント用であり、一方、 ``pygments.styles`` は " +"pygments スタイルを定義するクラスを提供するグループです。利用する側 (コン" +"シューマ) は、通常、期待するインタフェースを定義しています。衝突を避けるため" +"に、新しいグループを定義するのであればコンシューマは自身の PyPI での名前の後" +"に ``.`` を後置したもので始まるグループ名を使うべきです。グループ名は、ひとつ" +"かそれ以上の文字・数字・アンダースコアをドット文字で区切ったもの (正規表現で " +"``^\\w+(\\.\\w)*$``) でなければなりません。" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:42 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -"一般的な規則として、 :file:`direct_url.json` を生成する際には、インストーラは" -"可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 user:" -"password を環境変数から読み込むなら環境変数を参照するような URL として保存さ" -"れるべきであり、 ``requested_revision`` は要求された URL の中に出現するものを" -"極力そのまま反映するべきです。しかしながら、この情報は (``commit_id`` のよう" -"な) もっと精密なデータを使って *精製* されます。" - -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" -msgstr "pip コマンドの例と direct_url.json に与える影響" - -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" -msgstr "``direct_url.json`` を生成するコマンド:" +"グループ内では、エントリポイントを **name** で識別します。このことの正確な意" +"味は利用する側次第です。コンソールスクリプトでは、エントリポイントの名前はそ" +"のコマンドを起動するのに使われる名前です。配布物の内部では、エントリポイント" +"の名前は一意に決まるべきです。別の配布物が同じ名前を提供する場合には、利用す" +"る側でそのような衝突をどのように扱うのかを決めます。名前は ``=`` を除いてどん" +"な文字を含んでいても構いませんが、空白文字で始まったり終わったりすることはで" +"きず、 ``[`` で始まることもできません。エントリポイントをこれから作るのであれ" +"ば、文字・数字・アンダースコア・ドットとダッシュ (正規表現で言うと " +"``[\\w.-]+``) だけを用いることが推奨されています。" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" +"**object reference** は Python のオブジェクトを指し示しています。 " +"``importable.module`` 、または、 ``importable.module:object.attr`` の形式のい" +"ずれかです。ドットやコロンで区切られた各部分は、 Python の正当な識別子です。" +"次のようにルックアップされることを意図したものです::" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" +"とりわけそれがプログラムを起動する関数を指し示している場合には、いくつかの" +"ツールはこの種のオブジェクトへの参照、もっと良い用語で言えば 'エントリポイン" +"ト' を自分自身で呼び出します。" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:68 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"さらに追加のプロパティがあります: **extras** は、エントリポイントを提供する配" +"布物の追加的な機能をを識別する１組みの文字列です。もし指定されていれば、その" +"ような 'extras' の依存関係をエントリポイントが要求しています。メタデータの" +"フィールド :ref:`metadata_provides_extra` を見てください。" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" +"エントリポイント用に extras を使うことはもはや推奨されていません。利用する側" +"は、既存の配布物からそれを取り出して解析することをサポートするべきですが、し" +"かし、無視しても構いません。新しい公開用ツールは、 extras を指定することをサ" +"ポートする必要はありません。 extras を扱う機能は setuptools が 'egg' パッケー" +"ジを管理するモデルに紐づいたものですが、しかし、 pip や virtualenv のような" +"もっと新しいツールでは異なるモデルを採用しています。" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" -msgstr "" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "ファイルフォーマット" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (この場合、 ``url`` は git リポジトリのクローン先" -"のローカルディレクトリになり、 ``dir_info`` は ``\"editable\": true`` という" -"形で存在し、 ``vcs_info`` は設定されないということになるでしょう)" +"エントリポイントは、配布物の `*.dist-info` ディレクトリの中の :file:" +"`entry_points.txt` と呼ばれるファイル内で定義されます。これは、インストール済" +"みの配布物に関しては :ref:`インストール済みパッケージを記録する ` 、 wheels に関しては :ref:`バイナリ配布物のフォーマット " +"` に記述されます。このファイルでは UTF-8 エンコー" +"ディングを使います。" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" +"ファイルの内容は、 Python の :mod:`configparser` モジュールで読み取ることがで" +"きる INI フォーマットです。しかしながら、 configparser はデフォルトでは変数名" +"を大文字小文字の区別をせずに扱う一方で、エントリポイントでは区別をします。大" +"文字小文字の区別をする configparser はこのようにして作成できます::" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" -msgstr "``direct_url.json`` を *生成しない* コマンド" - -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" +"エントリポイントのファイルでは、名前と値を区切るのに常に ``=`` を使わなければ" +"なりません (他方で configparser は ``:`` で区切ることも許容します) 。" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" +"設定ファイルの各セクションはエントリポイントの各グループを表していて、名前は" +"名前であり、値はオブジェクトへの参照と任意の extras の両方をエンコードしま" +"す。 extras が使われる場合には、角括弧の中にコンマ区切りで列挙します。" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" -msgstr "歴史" - -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:105 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -"2020年3月: ``direct_url.json`` メタデータファイルは、当初は :pep:`610` で仕様" -"を指定されていましたが、ここで正式に文書化されました。" +"値の内部では、読み取る側はコロンの前後・オブジェクト参照と左角括弧の間・extra" +"の名前と角括弧や区切り文字のコロンの間・右角括弧の後にある空白文字 (連続する" +"複数の空白文字を含む) を許容し無視しなければなりません。 extras の文法は公式" +"に :pep:`508` の一部 (の ``extras`` 部分) として指定されており、値に関する制" +"限事項は :pep:`685` で指定されています。ファイルを書き出すようなツールでは、" +"オブジェクト参照と左角括弧の間に限って空白文字を挿入することが推奨されていま" +"す。" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" -msgstr "ダイレクト URL データ構造 " +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "スクリプト向けの使用法" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:130 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -"この説明文書では、python プロジェクトや VCS 上のソースツリーやローカルのソー" -"スツリーやソースコード配布物や wheel ファイルのような配布物アーティファクトに" -"対してURLを表現することを可能とする、 JSON のシリアル化抽象データ構造の仕様を" -"定義します。" +"``console_scripts`` と ``gui_scripts``: エントリポイントのふたつのグループ" +"は、パッケージング全体の中で特別な重要性を持っています。このふたつのグループ" +"では、エントリポイントの名前は、パッケージがインストールされた後にシステムの" +"シェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、こ" +"のコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数" +"は、プロセスの終了コードとして使われる整数を返しても構わず、 ``None`` を返す" +"と ``0`` を返したのと同じに扱われます。" -#: ../source/specifications/direct-url-data-structure.rst:12 -#, fuzzy -#| msgid "" -#| "The representation of the components of this data structure as a :rfc:" -#| "`1738` URL is not formally specified at time of writing. A common " -#| "representation is the pip URL format. Other examples are provided in :pep:" -#| "`440`." +#: ../source/specifications/entry-points.rst:138 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -"この :roc:`1738` URL としてのデータ構造の部分の表現方法は、本所執筆時点では、" -"公式に指定されていません。よくある表現方法は pip での URL フォーマットです。" -"他の例が :pep:`440` で提供されています。" +"例えば、 ``micmd = memo:main`` というエントリポイントは、 ``micmd`` というコ" +"マンドを生成し、このようにスクリプトを起動することになるでしょう::" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:145 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -"直接 URL データ構造は辞書でなければならず、 :rfc:`8259` に従って JSON にシリ" -"アライズできなければなりません。" +"``console_scripts`` と ``gui_scripts`` の違いは、 Windows システムにだけ影響" +"を与えます。 ``console_scripts`` はコンソールで実行できるようにラップされるの" +"で、コンソールに接続されて 入出力に``sys.stdin`` ・ ``sys.stdout`` ・ ``sys." +"stderr`` を使えるようになります。 ``gui_scripts`` は GUI で実行可能となるよう" +"にラップされるので、コンソールなしで起動することができ、しかし、アプリケー" +"ション側でリダイレクトして置かない限りは標準入出力を使うことができません。他" +"のプラットフォームではこのような区別をしません。" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/entry-points.rst:153 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -"それは少なくともふたつのフィールドを含んでいなければなりません。第１のフィー" -"ルドは ``string`` 型の ``url`` です。 ``url`` が何を参照しているかによって、" -"第２のフィールドは、 (``url`` が VCS への参照であるなら) ``vcs_info`` である" -"か、 (``url`` がソースコードのアーカイブまたは wheel を参照しているなら) " -"``archive_info`` であるか、または、 (``url`` がローカルのディレクトリを参照し" -"ているなら) ``dir_info`` であるかのうちのひとつでなければなりません。これらの" -"情報フィールドは、 (空であることも可能ですが) 以下に定義するような取り得る" -"キーを持った下位の辞書を値に取ります。" +"インストールツールは、 ``console_scripts`` と ``gui_scripts`` の両方につい" +"て、インストールスキームのスクリプト用ディレクトリにラッパをセットアップする" +"ものと期待されています。(しかし、インストールツールは) このディレクトリをコマ" +"ンドラインツールを探索するために定義される ``PATH`` 環境変数に入れることにつ" +"いては責任を持ちません。" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/entry-points.rst:158 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -"固持する場合には、``url`` は、セキュリティ上の理由から、機微に関わる認証情報" -"をすべて削除しておかなければなりません。" +"名前からファイルが作られることと、いくつかのファイルシステムでは大文字小文字" +"を区別しないことから、パッケージはこれらのグループについては大文字か小文字か" +"の違いしかないような名前を使うことを避けるべきです。名前が大文字小文字しか違" +"わない場合のインストールツールの挙動は未定義です。" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "外部から管理される環境" + +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -"しかしながら、次に述べる正規表現に合致する形で URL の user:password の部分を" -"環境変数から構成しても構いません::" +"Python の導入方法の中には Python をインストールするユーザが全てを管理するもの" +"もある一方で、(Linux ディストリビューションのオペレーティングシステムが提供す" +"るパッケージマネージャや、専用のインストーラを伴うアプリケーションにおけるバ" +"ンドルされた Python 環境のような) 別の手段で準備され管理されるものもありま" +"す。" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -"さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない" -"文字列であっても構いません。典型的な例としては、 ``ssh://git@gitlab.com/user/" -"repo`` のような URL における ``git`` を挙げることができます。" - -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" -msgstr "VCS URL群" +"そのような環境下で従来の Python のパッケージングツール類を使おうと試みること" +"は、最もうまくいったときでも混乱を招く結果になり、最悪の場合には根底にあるオ" +"ペレーティングシステム全体を完全に破壊してしまうことにもなりかねません。この" +"ような問題を解決する上では、説明文書と互換性ガイドだけが頼りになります。" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:18 +#, fuzzy msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -"``url`` が VCS リポジトリを参照している場合、 以下のキー群を伴った " -"``vcs_info`` キーが辞書に存在していなければなりません:" +":pep:`668` では ``EXTERNALLY-MANAGED`` マーカファイルを定義しており、これに" +"よって、Python をインストールする際に、 ``pip`` のような Python 特有のツール" +"に対してそのインタープリタのデフォルトのインストール環境にパッケージをインス" +"トールしたり削除したりしないように指示し、代わりにエンドユーザに対して :ref:`" +"仮想環境 ` を使う方向に向かうべきであると促すことができ" +"るようになります。" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -"(``git`` ・ ``hg`` ・ ``bzr`` ・ ``svn`` のいずれかのような) VCS の名前を含ん" -"だ ``vcs`` キー (``string`` 型) が存在していなければなりません。その他の VCS " -"については、この仕様を修正するための PEP を書くことによって登録されるべきで" -"す。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが " -"手を離してしまえるようにするために、 ``url`` の値は対応する VCS と齟齬のない" -"ものでなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:55 -msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -"``requested_revision`` キー (``string`` 型) は、ブランチ・タグ・リファレン" -"ス・コミット・リビジョンその他を指定するために存在していても構いません (VCS " -"と互換性を持つフォーマットにて)。" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -"``commit_id`` キー (``string`` 型) は、正確にどのコミットまたはリビジョンがイ" -"ンストールされた/されるかを示すもので、必須のキーです。 VCS がリビジョン識別" -"子に基づくコミットハッシュをサポートしているなら、インストールされたものの" -"ソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュを " -"``commit_id`` として使わなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "アーカイブ URL 群" +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +msgid "distro" +msgstr "配布物" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -"``url`` がソースコードのアーカイブや wheel ファイルを指し示す場合には、 " -"``archive_info`` キーが次のようなキーを持つ辞書の形で存在しなければなりませ" -"ん:" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -"``hashes`` キーは、ハッシュ名から16進数表記のファイルハッシュ値への対応を保持" -"する辞書として存在するべきです。" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -"複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何を" -"するか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何も" -"しなくても構いません) については利用する側次第です。" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." -msgstr "これらのハッシュの名前は、常に小文字に正規化されているべきです。" - -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -"``hash lib`` 経由で利用可能なハッシュアルゴリズム (とりわけ、 ``hashlib." -"new()`` に渡すことができて、かつ、追加的なパラメータを必要としないもの) はど" -"れでも、ハッシュ値を格納する辞書のキーとして用いることができます。 ``hashlib." -"algorithms_garanteed`` から安全なアルゴリズムを少なくともひとつ選択して (訳" -"注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点では、 ``sha256`` が特に" -"推奨されています。" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "packaging ライブラリ" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -"非推奨となった ``hash`` キー (``string`` 型) は、後方互換性を保つ目的でなら " -"``=`` を値に取る形で存在していても構いません。" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -"データ構造を生成する側では、ひとつまたは複数のハッシュが利用できるなら " -"``hashes`` キーを生成するべきです。以前からそうしていたので既存のクライアント" -"のために後方互換性を保つためなら、生成側は ``hash`` キーの生成を継続するべき" -"です。" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -"``hash`` と ``hashes`` の両方のキーが存在する時は、 ``hash`` キーの中に現れる" -"ハッシュは、 ``hashes`` の辞書の中にも存在しなければならず、そうすることで利" -"用する側では ``hashes`` キーがあればそれだけを考慮し、なければ ``hash`` に" -"フォールバックすることが可能になります。" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" -msgstr "ローカルディレクトリ" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +msgid "Python-specific package manager" +msgstr "conda クロスプラットフォームパッケージマネージャ" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -"``url`` がローカルのディレクトリを参照している場合には、以下のキーを含む辞書" -"として ``dir_info`` キーが存在していなければなりません。" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -"配布物が編集可能モードでインストールされた/される場合には ``editable`` " -"(``boolean`` 型): ``true`` 、そうでなければ ``false`` 。存在していない場合の" -"デフォルトは ``false`` です。" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -"``url`` がローカルのディレクトリを参照している場合、 :rfc:``8089` に適合する " -"``file`` スキームが存在していなければなりません。特にパス部分は絶対パスでなけ" -"ればなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはその" -"まま保存されているべきです。" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" -msgstr "サブディレクトリ内のプロジェクト群" +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "macOS インストーラとパッケージマネージャ" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -"トップレベルの ``subdirectory`` フィールドは、 ``pyproject.toml`` または " -"``setup.py`` が存在する場所を指定するために、 VCS リポジトリやソースコードの" -"アーカイブやローカルのディレクトリのルートディレクトリに対する相対パスとして" -"示したディレクトリパスを値とするものとして存在することが許されています。" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" -msgstr "登録済みの VCS" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -"この節では登録済み VCS; ``vcs`` や ``requested_revision`` やその他の " -"``vcs_info`` 内のフィールドや、さらにある場合には特定の VCS に特有のフィール" -"ドなどの使い方のような拡張された VCS 特有の情報 の一覧を示します。 PEP を書く" -"ことでこの仕様を修正する形で別の VCS を登録することが推奨されていますが、ツー" -"ルの側で他の VCS を (訳注、VCS 登録作業抜きで) サポートしても構いません。 " -"``vcs`` フィールドの値は、 (小文字の) コマンド名であるべきです。当該 VCS をサ" -"ポートするのに必要であると思われるその他のフィールドについては、当該 VCS のコ" -"マンド名で始まる名前にするべきです。" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" -msgstr "Git" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" -msgstr "ホームページ" +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" -msgstr "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +msgid "This specification is twofold." +msgstr "PyPA 仕様" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" -msgstr "vcs コマンド" +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" -msgstr "git" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" -msgstr "``vcs`` フィールド" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" -msgstr "``requested_revision`` フィールド" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -"タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その" -"他のコミットハッシュ的なもの。" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" -msgstr "``commit_id`` フィールド" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." -msgstr "コミットハッシュ (16進数で40文字のSHA1)。" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:173 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -"ツールは、 ``requested_revision`` が Git 参照に対応しているか否かを判断するた" -"めに ``git show-ref`` や ``git symbolic-ref`` コマンドを使うことができます。" -"さらに、 ``refs/tags/`` で始まる参照はタグに対応し、クローンした後に ``refs/" -"remotes/origin/`` で始まる参照はブランチに対応します。" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" -msgstr "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" -msgstr "hg" - -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." -msgstr "タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。" - -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." -msgstr "チェンジセット ID (16 進数で 40 文字)。" - -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" -msgstr "Bazaar" - -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" -msgstr "https://www.breezy-vcs.org/" - -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" -msgstr "bzr" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." -msgstr "タグ名・ブランチ名・リビジョン id 。" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." -msgstr "リビジョン id 。" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" -msgstr "svn" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -"``requested_revision`` は、 ``svn checkout`` ``--revision`` オプションと互換" -"でなければなりません。 Subversion では、ブランチまたはタグは ``url`` の一部で" -"す。" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:255 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -"Subversion は大域的にユニークな識別子をサポートしていないので、このフィールド" -"は当該リポジトリにおける Subversion のリビジョン番号です。" - -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" -msgstr "ソースコードアーカイブ:" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" -msgstr "タグおよびコミットハッシュ付きの Git のURL:" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" -msgstr "ローカルディレクトリ:" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" -msgstr "編集可能モード状態にあるローカルディレクトリ:" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -"2020年3月: このデータ構造は、当初は :pep:`610` で ``direct_url.json`` メタ" -"データファイルの一部として仕様を指定されていましたが、ここで正式に文書化され" -"ました。" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -"2023年1月: ``archive_info.hashes`` キーを追加しました ([議論] (https://" -"discuss.python.org/t/22299)) 。" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" -msgstr "エントリポイントの仕様" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "仮想環境のランタイムを識別する" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -"*エントリポイント* は、インストールされた配布物が他のプログラムから発見され使" -"用されるように提供するコンポーネントを広報するためのメカニズムです。例えば:" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -"配布物では、それぞれが関数を参照するような ``console_scripts`` エントリポイン" -"トを指定することができます。 *pip* (または console_scripts を認識する他のイン" -"ストーラ) が配布物をインストールする際に、各エントリポイントのコマンドライン" -"ラッパを生成します。" -#: ../source/specifications/entry-points.rst:14 -msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -"アプリケーションは、プラグインをロードするためにエントリポイントを用いること" -"ができます; 例えば、 Pygments (シンタックスハイライトを行うツール) は追加的な" -"字句解析器を使うことが可能であり、また、別にインストールされたパッケージから" -"提供されるスタイルを使うことができます。この件の詳細については、 :doc:`/" -"guides/creating-and-discovering-plugins` を見てください。" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -"エントリポイントのファイルフォーマットは、元々は、 setuptools でビルドされた" -"パッケージが、動作時 (ランタイム) に ``importlib.metadata`` で読み取られるで" -"あろうと思われるインテグレーションポイントメタデータを提供できるようにと開発" -"されました。現在では、 setuptools 以外のビルドツールが ``importlib." -"metadata`` と互換性のあるエントリポイントのメタデータを公開し、 ``importlib." -"metadata`` 以外のランタイムライブラリが移植可能な形で公開されているエントリポ" -"イントのメタデータを (潜在的には、たとえ異なるキャッシングと衝突回避の戦略を" -"採用していたとしても) 読み取ることができるようにと PyPA 相互互換性仕様におい" -"て定義されています。" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "データモデル" - -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -"概念的に、エントリポイントは３個の属性を持たなければならないと定義されていま" -"す:" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -"エントリポイントが属する *group* は、それがどのような種類のオブジェクトを提供" -"するのかを示します。例えば、 ``console_scripts`` グループはコマンドとして使え" -"る関数を参照するエントリポイント用であり、一方、 ``pygments.styles`` は " -"pygments スタイルを定義するクラスを提供するグループです。利用する側 (コン" -"シューマ) は、通常、期待するインタフェースを定義しています。衝突を避けるため" -"に、新しいグループを定義するのであればコンシューマは自身の PyPI での名前の後" -"に ``.`` を後置したもので始まるグループ名を使うべきです。グループ名は、ひとつ" -"かそれ以上の文字・数字・アンダースコアをドット文字で区切ったもの (正規表現で " -"``^\\w+(\\.\\w)*$``) でなければなりません。" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -"グループ内では、エントリポイントを **name** で識別します。このことの正確な意" -"味は利用する側次第です。コンソールスクリプトでは、エントリポイントの名前はそ" -"のコマンドを起動するのに使われる名前です。配布物の内部では、エントリポイント" -"の名前は一意に決まるべきです。別の配布物が同じ名前を提供する場合には、利用す" -"る側でそのような衝突をどのように扱うのかを決めます。名前は ``=`` を除いてどん" -"な文字を含んでいても構いませんが、空白文字で始まったり終わったりすることはで" -"きず、 ``[`` で始まることもできません。エントリポイントをこれから作るのであれ" -"ば、文字・数字・アンダースコア・ドットとダッシュ (正規表現で言うと " -"``[\\w.-]+``) だけを用いることが推奨されています。" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -"**object reference** は Python のオブジェクトを指し示しています。 " -"``importable.module`` 、または、 ``importable.module:object.attr`` の形式のい" -"ずれかです。ドットやコロンで区切られた各部分は、 Python の正当な識別子です。" -"次のようにルックアップされることを意図したものです::" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -"とりわけそれがプログラムを起動する関数を指し示している場合には、いくつかの" -"ツールはこの種のオブジェクトへの参照、もっと良い用語で言えば 'エントリポイン" -"ト' を自分自身で呼び出します。" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -"さらに追加のプロパティがあります: **extras** は、エントリポイントを提供する配" -"布物の追加的な機能をを識別する１組みの文字列です。もし指定されていれば、その" -"ような 'extras' の依存関係をエントリポイントが要求しています。メタデータの" -"フィールド :ref:`metadata_provides_extra` を見てください。" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -"エントリポイント用に extras を使うことはもはや推奨されていません。利用する側" -"は、既存の配布物からそれを取り出して解析することをサポートするべきですが、し" -"かし、無視しても構いません。新しい公開用ツールは、 extras を指定することをサ" -"ポートする必要はありません。 extras を扱う機能は setuptools が 'egg' パッケー" -"ジを管理するモデルに紐づいたものですが、しかし、 pip や virtualenv のような" -"もっと新しいツールでは異なるモデルを採用しています。" - -#: ../source/specifications/entry-points.rst:80 -msgid "File format" -msgstr "ファイルフォーマット" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -"エントリポイントは、配布物の `*.dist-info` ディレクトリの中の :file:" -"`entry_points.txt` と呼ばれるファイル内で定義されます。これは、インストール済" -"みの配布物に関しては :ref:`インストール済みパッケージを記録する ` 、 wheels に関しては :ref:`バイナリ配布物のフォーマット " -"` に記述されます。このファイルでは UTF-8 エンコー" -"ディングを使います。" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -"ファイルの内容は、 Python の :mod:`configparser` モジュールで読み取ることがで" -"きる INI フォーマットです。しかしながら、 configparser はデフォルトでは変数名" -"を大文字小文字の区別をせずに扱う一方で、エントリポイントでは区別をします。大" -"文字小文字の区別をする configparser はこのようにして作成できます::" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -"エントリポイントのファイルでは、名前と値を区切るのに常に ``=`` を使わなければ" -"なりません (他方で configparser は ``:`` で区切ることも許容します) 。" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -"設定ファイルの各セクションはエントリポイントの各グループを表していて、名前は" -"名前であり、値はオブジェクトへの参照と任意の extras の両方をエンコードしま" -"す。 extras が使われる場合には、角括弧の中にコンマ区切りで列挙します。" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "文書の類型" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -"値の内部では、読み取る側はコロンの前後・オブジェクト参照と左角括弧の間・extra" -"の名前と角括弧や区切り文字のコロンの間・右角括弧の後にある空白文字 (連続する" -"複数の空白文字を含む) を許容し無視しなければなりません。 extras の文法は公式" -"に :pep:`508` の一部 (の ``extras`` 部分) として指定されており、値に関する制" -"限事項は :pep:`685` で指定されています。ファイルを書き出すようなツールでは、" -"オブジェクト参照と左角括弧の間に限って空白文字を挿入することが推奨されていま" -"す。" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "例えば::" +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" -msgstr "スクリプト向けの使用法" +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "はい (``python -m pip uninstall``)" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -"``console_scripts`` と ``gui_scripts``: エントリポイントのふたつのグループ" -"は、パッケージング全体の中で特別な重要性を持っています。このふたつのグループ" -"では、エントリポイントの名前は、パッケージがインストールされた後にシステムの" -"シェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、こ" -"のコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数" -"は、プロセスの終了コードとして使われる整数を返しても構わず、 ``None`` を返す" -"と ``0`` を返したのと同じに扱われます。" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -"例えば、 ``micmd = memo:main`` というエントリポイントは、 ``micmd`` というコ" -"マンドを生成し、このようにスクリプトを起動することになるでしょう::" -#: ../source/specifications/entry-points.rst:143 -msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -"``console_scripts`` と ``gui_scripts`` の違いは、 Windows システムにだけ影響" -"を与えます。 ``console_scripts`` はコンソールで実行できるようにラップされるの" -"で、コンソールに接続されて 入出力に``sys.stdin`` ・ ``sys.stdout`` ・ ``sys." -"stderr`` を使えるようになります。 ``gui_scripts`` は GUI で実行可能となるよう" -"にラップされるので、コンソールなしで起動することができ、しかし、アプリケー" -"ション側でリダイレクトして置かない限りは標準入出力を使うことができません。他" -"のプラットフォームではこのような区別をしません。" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "はい (``python -m pip uninstall``)" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -"インストールツールは、 ``console_scripts`` と ``gui_scripts`` の両方につい" -"て、インストールスキームのスクリプト用ディレクトリにラッパをセットアップする" -"ものと期待されています。(しかし、インストールツールは) このディレクトリをコマ" -"ンドラインツールを探索するために定義される ``PATH`` 環境変数に入れることにつ" -"いては責任を持ちません。" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -"名前からファイルが作られることと、いくつかのファイルシステムでは大文字小文字" -"を区別しないことから、パッケージはこれらのグループについては大文字か小文字か" -"の違いしかないような名前を使うことを避けるべきです。名前が大文字小文字しか違" -"わない場合のインストールツールの挙動は未定義です。" - -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" -msgstr "外部から管理される環境" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -"Python の導入方法の中には Python をインストールするユーザが全てを管理するもの" -"もある一方で、(Linux ディストリビューションのオペレーティングシステムが提供す" -"るパッケージマネージャや、専用のインストーラを伴うアプリケーションにおけるバ" -"ンドルされた Python 環境のような) 別の手段で準備され管理されるものもありま" -"す。" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -"そのような環境下で従来の Python のパッケージングツール類を使おうと試みること" -"は、最もうまくいったときでも混乱を招く結果になり、最悪の場合には根底にあるオ" -"ペレーティングシステム全体を完全に破壊してしまうことにもなりかねません。この" -"ような問題を解決する上では、説明文書と互換性ガイドだけが頼りになります。" -#: ../source/specifications/externally-managed-environments.rst:18 -#, fuzzy -#| msgid "" -#| ":pep:`668` defined an ``EXTERNALLY-MANAGED`` marker file that allows a " -#| "Python installation to indicate to Python-specific tools such as ``pip`` " -#| "that they neither install nor remove packages into the interpreter’s " -#| "default installation environment, and should instead guide the end user " -#| "towards using :ref:`virtual-environments`." -msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." -msgstr "" -":pep:`668` では ``EXTERNALLY-MANAGED`` マーカファイルを定義しており、これに" -"よって、Python をインストールする際に、 ``pip`` のような Python 特有のツール" -"に対してそのインタープリタのデフォルトのインストール環境にパッケージをインス" -"トールしたり削除したりしないように指示し、代わりにエンドユーザに対して :ref:`" -"仮想環境 ` を使う方向に向かうべきであると促すことができ" -"るようになります。" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "著作権" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "PyPA 仕様" + +#: ../source/specifications/index.rst:6 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" +"これは、 Python パッケージングオーソリティが維持管理している現時点で有効な相" +"互互換性の使用です。これらの標準を更新し新たな標準を提案するプロセスは、 " +"`pypa.io `__ に文書化されてい" +"ます。" -#: ../source/specifications/externally-managed-environments.rst:61 +#: ../source/specifications/inline-script-metadata.rst:3 #, fuzzy -#| msgid "distribution" -msgid "distro" -msgstr "配布物" +msgid "Inline script metadata" +msgstr "プロジェクトのメタデータを宣言する" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "packaging ライブラリ" +#: ../source/specifications/inline-script-metadata.rst:33 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "The conda cross-platform package manager" -msgid "Python-specific package manager" -msgstr "conda クロスプラットフォームパッケージマネージャ" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 +#: ../source/specifications/inline-script-metadata.rst:79 #, fuzzy -#| msgid "macOS installers and package managers" -msgid "distro package manager" -msgstr "macOS インストーラとパッケージマネージャ" +msgid "pyproject type" +msgstr "pyproject.toml" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -#, fuzzy -#| msgid "PyPA specifications" -msgid "This specification is twofold." -msgstr "PyPA 仕様" - -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" +msgstr "例" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +msgid "Reference Implementation" +msgstr "文書の類型" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +msgid "Recommendations" +msgstr "オススメのツール" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" -msgstr "" +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" +msgstr "パッケージ名の正規化" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" +"プロジェクト名は、さまざまな文脈で使用するために \"正規化\" されます。この説" +"明文書では、プロジェクト名がどのように正規化されるべきかについて記述します。" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." -msgstr "" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "正当な非正規化名" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" +"正当な名前は ASCII 文字・数字・ピリオド・アンダースコア・ハイフンだけで構成さ" +"れているものです。名前の先頭と末尾は文字か数字でなければなりません。正当なプ" +"ロジェクト名は、次の正規表現に (``re.IGNORECASE`` 付きで) マッチするものに限" +"らるということになります::" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" +msgstr "正規化" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" +"名前は、すべての文字を小文字にして、 ``.`` ・ ``,`` ・ ``_`` の文字が連続で１" +"個以上出現したらそれを単独の ``-`` の文字に置き換えるべきです。これは、 " +"Python の re モジュールを使って実装することができます:" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" -msgstr "" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" +msgstr "次に挙げる名前はすべて同等ということになります:" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." -msgstr "" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" +msgstr "``friendly-bard`` (正規化形式)" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" -msgstr "" +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" +msgstr "``Friendly-Bard``" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." -msgstr "" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" +msgstr "``FRIENDLY-BARD``" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -#| msgid "Runtime detection of virtual environments" -msgid "Guide users towards virtual environments" -msgstr "仮想環境のランタイムを識別する" +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" +msgstr "``friendly.bard``" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" +msgstr "``friendly_bard``" + +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "``friendly--bard``" + +#: ../source/specifications/name-normalization.rst:39 +#, fuzzy msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." -msgstr "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "``FrIeNdLy-._.-bArD`` (ひどい書き方の名前の例だが、正当である)" -#: ../source/specifications/externally-managed-environments.rst:293 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" +"`2015年9月 `_: 正規化された名称は、元々は :pep:`503#normalized-" +"names` で仕様化されていました。" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" +"`2015年11月 `_: 正当であるが正規化されてはいない名称は、元々は :pep:" +"`508#names` で仕様化されていました。" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "プラットフォームの互換性タグ" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" +"プラットフォーム相互互換性タグは、特定のプラットフォームと互換であるとビルド" +"ツールが配布物に印を付けることができるようにし、インストーラが自身が動作して" +"いるシステムと互換であるのはどの配布物であるかを理解できるようにします。" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" +msgstr "この仕様に貢献する PEP 群を以下に示す:" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" +msgstr ":pep:`425`" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" +msgstr ":pep:`513`" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" +msgstr ":pep:`571`" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" +msgstr ":pep:`599`" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" +msgstr ":pep:`600`" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "タグの書式は、 ``{python tag}-{abi tag}-{platform tag}`` です。" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" +msgstr "python タグ" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" +msgstr "'py27' ・ 'cp33'" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "文書の類型" +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" +msgstr "'cp33dmu' ・ 'none'" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" +msgstr "'linux_x86_64' ・ 'any'" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" +"例えば、``py27-none-any`` というタグは、abi に対する要求なしに任意のプラット" +"フォームで Python 2.7 (任意の Python 2.7 実装) との互換性を持つことを意味しま" +"す。" -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``pip install``" -msgstr "はい (``python -m pip uninstall``)" +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "使い方" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" +"``wheel`` ビルド済みパッケージのフォーマットは、ファイル名の中にこのようなタ" +"グを ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl`` の形で包含しています。他のパッケージフォーマットにはそれ" +"ぞれ独自の慣習があるかもしれません。" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" +"どのようなタグであれ、その中に潜在的に含まれる空白文字は ``_`` で置換されるべ" +"きです。" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``pip install --user``" -msgstr "はい (``python -m pip uninstall``)" - -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" +msgstr "Python タグ" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" +"Python タグは、配布物が必要とする実装やバージョンを示します。主要な実装には短" +"縮系のコードがあって、当初は:" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: 一般的な Python (実装に特有な機能を要求しません)" -#: ../source/specifications/externally-managed-environments.rst:445 -msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" +msgstr "cp: CPython" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" +msgstr "ip: IronPython" -#: ../source/specifications/externally-managed-environments.rst:466 -msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" +msgstr "pp: PyPy" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" +msgstr "jy: Jython" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" -msgstr "PyPA 仕様" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." +msgstr "ほかの Python 実装には ``sys.implementation.name`` を用いるべきです。" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -"これは、 Python パッケージングオーソリティが維持管理している現時点で有効な相" -"互互換性の使用です。これらの標準を更新し新たな標準を提案するプロセスは、 " -"`pypa.io `__ に文書化されてい" -"ます。" - -#: ../source/specifications/inline-script-metadata.rst:3 -#, fuzzy -#| msgid "Declaring project metadata" -msgid "Inline script metadata" -msgstr "プロジェクトのメタデータを宣言する" +"バージョンは ``py_version_nodot`` です。 CPython は no dot にせずに済ませます" +"が、必要な場合には代わりにアンダースコア文字 ``_`` が使用されます。 PyPy は、" +"おそらく、ここに ``pp18`` や ``pp19`` といったそれ自身のバージョンを使いま" +"す。" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" +"多くの純 Python 配布物では、バージョンは ``2`` や ``3`` や ``py2`` ・ " +"``py3`` といったメジャーバージョンだけにしておくことができます。" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" +"重要なことは、 ``py2`` や ``py3`` のような major-version-only タグは " +"``py20`` や ``py30`` の短縮形であるわけではないということです。そうではなく" +"て、これらのタグは、パッケージ作成者がいくつものバージョンに互換性を持つ配布" +"物を意図的にリリースしたのです。" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" +"単一ソースで Python 2/3 に互換性を持つ配布物は、合成タグ ``py2.py3`` を用いる" +"ことができます。 後述の `タグの圧縮された組み合わせ `_ " +"を参照してください。" -#: ../source/specifications/inline-script-metadata.rst:25 -msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "ABI タグ" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" +"ABI タグは、いずれかの拡張モジュールによってどのような Python ABI が要求され" +"ているのかを示します。実装依存の ABI 群については、実装 (の名前) は、たとえ" +"ば ``cp33d`` がデバッグオプション付きの CPython 3.3 ABI のことを指すように、 " +"Python タグと同様のやり方で短縮したものを使います。" -#: ../source/specifications/inline-script-metadata.rst:40 -msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" +"CPython の安定版 ABI のことは、共有ライブラリの拡張子と同様に ``abi3`` と書き" +"ます。" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" +"非常に不安定な ABI を持つ実装は、そのソースコードのリビジョンやコンパイラフラ" +"グその他の SHA-256 ハッシュ値の最初の６バイトを (BASE64にエンコードされた８文" +"字として) 用いても構いませんが、おそらくはバイナリ配布物を配布することには大" +"きな需要はないでしょう。それぞれの実装のコミュニティで ABI タグをどのように用" +"いるのが最適かを決定すればよいでしょう。" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "プラットフォームタグ" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" +"プラットフォームタグは、すべてのハイフン ``-`` とピリオド ``.`` をアンダース" +"コア ``_`` で単純に置き換えた ``sysconfig.get_platform()`` です。 :ref:" +"`distutils` が Python 3.12 で削除されるまでは、これは ``distutils.util." +"get_platform()`` でした。" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" +msgstr "win32" + +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" +msgstr "linux_i386" + +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" +"Linux プラットフォームのエコシステムが巨大であることとそれらの間に微妙な差異" +"があることから、 :pep:`425` で定義されたスキームは、Linux プラットフォーム向" +"けの wheel ファイル (および、一般に \\*nix 向けの wheel ファイル) の公開配布" +"物としては不十分です。" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" +"代わりに、 :pep:`600` で Linux プラットフォームの共通のサブセットを表現する" +"``manylinux`` 標準が定義されており、普通の Linux ディストロのほとんどで使え" +"る ``manylinux`` プラットフォームタグ付きの wheel をビルドできるようにしてい" +"ます。" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" +"``manylinux`` 仕様は複数回の改訂があり、それぞれの版がその時々の Linux の共通" +"のサブセットを表現しています:" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" +"``manylinux1`` (:pep:`513`) は、 ``x86_64`` および ``i686`` アーキテクチャを" +"サポートしていて、 2007 年から互換性のある Linux プラットフォームに基づいてい" +"ます。" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" - -#: ../source/specifications/inline-script-metadata.rst:81 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" +"``manylinux2010`` (:pep:`571`) は、 ``x86_64`` および ``i686`` アーキテクチャ" +"をサポートしており、以前の仕様を更新して、その代わりに 2010 年から互換性のあ" +"る Linux プラットフォームに基づいています。" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" +"``manylinux2014`` (:pep:`599`) では、多数のアーキテクチャ (``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``) へのサポートを追加し、ま" +"た、2014 年以降の互換 Linux プラットフォームのベースを更新しました。" -#: ../source/specifications/inline-script-metadata.rst:86 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" +"``manylinux_x_y`` (:pep:`600`) では、それまでの PEP 群を全て代替する形で将来" +"を見据えた標準を定義しました。 ``x`` と ``y`` は、その標準がサポートする " +"glibc のメジャーバージョンとマイナーバージョンとして定義されています (例え" +"ば、 ``manylinux_2_24`` は glibc 2.24+ を使っているディストロならどれでも、そ" +"の上で動作するはずです) 。以前に使われたタグは広報互換性を保つために依然とし" +"てサポートされています。" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:137 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" +"一般に、古めのバージョンの仕様向けにビルドされた配布物には前方互換性がありま" +"す (というのは、 ``manylinux1`` の配布物はより新しいシステムでも同様に動作す" +"るはずだということです) が、後方互換性はありません (``manylinux2010`` の配布" +"物が 2010 年よりも前に存在していたプラットフォームで動作するとは想定されてい" +"ないということです) 。" -#: ../source/specifications/inline-script-metadata.rst:91 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" +"``manylinux1`` と ``manylinux2010`` は既に end-of-life に達していて、提供され" +"ているビルド環境にはもはやセキュリティアップデートが提供されることはないであ" +"ろうという警告されていることもあって、パッケージ保守者は最も互換性のある仕様" +"をターゲットにするように努力するべきです。" -#: ../source/specifications/inline-script-metadata.rst:94 +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" +msgstr "Manylinux 互換性サポート" + +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" +"``manylinux2014`` 仕様は相対的に新しく、未だインストールツールに広く認識され" +"たと言える状況ではありません。" -#: ../source/specifications/inline-script-metadata.rst:98 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" +"``manylinux_x_y`` 仕様は相対的に新しく、未だインストールツールに広く認識され" +"たと言える状況ではありません。" -#: ../source/specifications/inline-script-metadata.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" +"適切なプロジェクトがサポートするさまざまな ``manylinux`` 標準の最低限のバー" +"ジョンを次に掲げる表に示します:" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" -msgstr "例" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" +msgstr "ツール" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" +msgstr "``manylinux1``" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "文書の類型" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" +msgstr "``>=19.0``" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" +msgstr "``>=19.3``" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Tool recommendations" -msgid "Recommendations" -msgstr "オススメのツール" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" +msgstr "``>=20.3``" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" +msgstr "auditwheel" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" -msgstr "パッケージ名の正規化" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -"プロジェクト名は、さまざまな文脈で使用するために \"正規化\" されます。この説" -"明文書では、プロジェクト名がどのように正規化されるべきかについて記述します。" +"audit wheel 3.3.0 では ``manylinux_2_24`` へのサポートだけが追加されました" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" -msgstr "正当な非正規化名" +#: ../source/specifications/platform-compatibility-tags.rst:172 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" +"タグ類は、 (もしダウンロードが必要なら) 選択可能なビルド済配布物のリストの中" +"からどれをダウンロードするのかをインストーラが決定するために使われます。イン" +"ストーラは、自身がサポートする (pyver, abi, arch) タプルのリストを維持管理し" +"ています。ビルド済配布物のタグがリストに含まれて (``in`` ) いれば、それをイン" +"ストールすることができます。" -#: ../source/specifications/name-normalization.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -"正当な名前は ASCII 文字・数字・ピリオド・アンダースコア・ハイフンだけで構成さ" -"れているものです。名前の先頭と末尾は文字か数字でなければなりません。正当なプ" -"ロジェクト名は、次の正規表現に (``re.IGNORECASE`` 付きで) マッチするものに限" -"らるということになります::" +"古い Python リリース向けに発行された純 Python のバージョンにフォールバックす" +"るよりも前に、利用できる中で最も機能を網羅したビルド済配布物 (インストールす" +"る先の環境に最も適したもの) をインストーラがデフォルトで選択することが推奨さ" +"れています。インストーラは、また、受け入れ可能な互換性タグのリストを設定変更" +"したり順序を入れ替えたりする方法を持つことが推奨されています; 例えば、ユーザ" +"は、純 Python であると広報しているビルド済みパッケージだけをダウンロードする" +"ために、 ``*-none-any`` タグだけを受容しても構いません。" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" -msgstr "正規化" +#: ../source/specifications/platform-compatibility-tags.rst:186 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" +"互換性はあるがもはや古くなってしまったビルド済みのものを使う選択肢よりもより" +"好ましいという点で、インストーラに望まれるもうひとつの機能は \"可能ならソース" +"コードから再コンパイルする\" でしょう。" -#: ../source/specifications/name-normalization.rst:22 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -"名前は、すべての文字を小文字にして、 ``.`` ・ ``,`` ・ ``_`` の文字が連続で１" -"個以上出現したらそれを単独の ``-`` の文字に置き換えるべきです。これは、 " -"Python の re モジュールを使って実装することができます:" +"この事例集は、インストーラを linux_x86_64 システム上の CPython 3.3 のもとで走" +"らせるためのものです。最も好ましいもの (最新版の Python 向けにビルドされたコ" +"ンパイル済みの拡張モジュールが付属している配布物) から、最も好ましくはないも" +"の (古いバージョンの Python でビルドされた純 Python の配布物) へ、という順序" +"で並んでいます:" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" -msgstr "次に挙げる名前はすべて同等ということになります:" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" -msgstr "``friendly-bard`` (正規化形式)" - -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" -msgstr "``Friendly-Bard``" - -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" -msgstr "``FRIENDLY-BARD``" - -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" -msgstr "``friendly.bard``" - -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" -msgstr "``friendly_bard``" - -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" -msgstr "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" -#: ../source/specifications/name-normalization.rst:39 -#, fuzzy -#| msgid "" -#| "``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid)" -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" -msgstr "``FrIeNdLy-._.-bArD`` (ひどい書き方の名前の例だが、正当である)" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" -#: ../source/specifications/name-normalization.rst:44 -msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." -msgstr "" -"`2015年9月 `_: 正規化された名称は、元々は :pep:`503#normalized-" -"names` で仕様化されていました。" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" -#: ../source/specifications/name-normalization.rst:45 -msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." -msgstr "" -"`2015年11月 `_: 正当であるが正規化されてはいない名称は、元々は :pep:" -"`508#names` で仕様化されていました。" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" -msgstr "プラットフォームの互換性タグ" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" -#: ../source/specifications/platform-compatibility-tags.rst:8 -msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" -"プラットフォーム相互互換性タグは、特定のプラットフォームと互換であるとビルド" -"ツールが配布物に印を付けることができるようにし、インストーラが自身が動作して" -"いるシステムと互換であるのはどの配布物であるかを理解できるようにします。" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" -msgstr "この仕様に貢献する PEP 群を以下に示す:" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" +msgstr "cp33-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" -msgstr ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" +msgstr "cp3-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" -msgstr ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" +msgstr "py33-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" -msgstr ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" +msgstr "py3-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" -msgstr ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" +msgstr "py32-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" -msgstr ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" +msgstr "py31-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." -msgstr "タグの書式は、 ``{python tag}-{abi tag}-{platform tag}`` です。" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" +msgstr "py30-none-any" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" -msgstr "python タグ" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" +"ビルド済み配布物は、サブプロセスとして起動されるネーティブの実行可能ファイル" +"を含んでいるなどのようなC 言語拡張以外の理由によって、特定のプラットフォーム" +"向けであっても構いません。" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" -msgstr "'py27' ・ 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" +"時々、あるパッケージの特定のバージョンとして複数のビルド済み配布物が存在する" +"ことがあるでしょう。例えば、パッケージ製作者が、 ``cp33-abi3-linux_x86_64`` " +"というタグを付けて追加的な C 言語拡張を含むパッケージをリリースし、そのような" +"ものを含まない同じ配布物に ``py3-none-any`` というタグを付けてリリースするよ" +"うな場合です。(このような場合でも) サポートされるタグのリストで先に出現する方" +"を優先するという理由によって C 言語拡張付きのパッケージがそうでないパッケージ" +"よりも選好されてインストールされるという形で、インデックスによってどちらかに" +"決めることができます。" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" -msgstr "'cp33dmu' ・ 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" +msgstr "圧縮されたタグのセット" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" -msgstr "'linux_x86_64' ・ 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" +msgstr "" +"bdists のコンパクトなファイル名で、互換性のあるタグトリプルが複数ある場合にも" +"きちんと動作するものを許容するためには、代わりにファイル名の中のそれぞれのタ" +"グが '.' で分割可能でありソート可能であるような一連のタグになっていることが可" +"能です。例えば、 pip は純 Python のパッケージで、同一のソースコードで Python " +"2 でも 3 でも動作するように書かれていますが、これは ``py2.py3-none-any`` とい" +"うタグを付けた bdist として配布することができるでしょう。単純なタグの完全なリ" +"ストは::" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -"例えば、``py27-none-any`` というタグは、abi に対する要求なしに任意のプラット" -"フォームで Python 2.7 (任意の Python 2.7 実装) との互換性を持つことを意味しま" -"す。" +"このスキームを実装する bdist フォーマットは、拡張されたタグ群を bdist に特有" +"のメタデータの中に含んでいるべきです。この圧縮スキームは、サポートされていな" +"いタグや例えば \"cp33-cp31u-win64\" のようにいかなる Python 実装においてもサ" +"ポートされていない \"不可能な\" タグを大量に生成すると思われるので、控えめに" +"使うようにしてください。" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" -msgstr "使い方" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" +msgstr "デフォルトではどんなタグが使われますか？" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -"``wheel`` ビルド済みパッケージのフォーマットは、ファイル名の中にこのようなタ" -"グを ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl`` の形で包含しています。他のパッケージフォーマットにはそれ" -"ぞれ独自の慣習があるかもしれません。" +"ツール類は、 ``cp33-cp33m-win32`` のようなアーキテクチャへの依存を示すタグや " +"``py33-none-any`` のような純 Python タグの中で最も好ましいものをデフォルトで" +"採用するべきです。パッケージ製作者がデフォルトをオーバーライドしていたとすれ" +"ば、それは彼らが異なる Python 間での互換性を提供しようという意図があったこと" +"を示しています。" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -"どのようなタグであれ、その中に潜在的に含まれる空白文字は ``_`` で置換されるべ" -"きです。" - -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" -msgstr "Python タグ" +"自分の配布物が最新版の Python と相容れない機能を使っているとしたら、どんなタ" +"グを使いますか？" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -"Python タグは、配布物が必要とする実装やバージョンを示します。主要な実装には短" -"縮系のコードがあって、当初は:" +"互換性タグは、インストーラがある配布物の *単一のバージョン* の *最も互換性が" +"ある* ビルドを選択する際に助けとなります。例えば、 (Python 3.4 に特有の機能を" +"使っている) ``beaglevote-1.2.0``には Python 3.3 と互換性を持つビルドがひとつ" +"もないという場合でも、 ``py34-none-any`` タグの代わりに ``py3-none-any`` タグ" +"を使っても構いません。 Python 3.3 のユーザが互換性のあるビルドを得るために" +"は、新しい機能を使う前のリリースである ``beaglevote-1.1.0`` 用の要求 " +"(requirement) などを他の指定子を組み合わせなければなりません。" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" -msgstr "py: 一般的な Python (実装に特有な機能を要求しません)" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "Python のバージョン番号に ``.`` がないのはなぜですか?" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" -msgstr "cp: CPython" - -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" -msgstr "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" +"CPython は、数字３個のメジャーリリースなしで 20 年以上にわたって存続してきま" +"した。これはしばらくの間は続くに違いありません。 - や . が周辺のファイル名を" +"区切る役割を果たしているので、他の実装では _ を区切り子として使っても構いませ" +"ん。" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" -msgstr "pp: PyPy" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" +"ハイフンやその他の英数字以外の文字をアンダースコアに正規化するのはなぜですか?" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" -msgstr "jy: Jython" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" +"ファイル名の部分部分を区分けする ``.`` 文字や ``-`` 文字との干渉を避けるため" +"に、かつ、 (クォートすることなく URL パス内で使用可能であることを含む) 数多あ" +"るファイルシステムのファイル名に対する制限事項との間のより良い互換性のため" +"に。" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." -msgstr "ほかの Python 実装には ``sys.implementation.name`` を用いるべきです。" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "何故、 ``.`` や ``-`` の代わりに特殊な文字 を使わないのですか？" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -"バージョンは ``py_version_nodot`` です。 CPython は no dot にせずに済ませます" -"が、必要な場合には代わりにアンダースコア文字 ``_`` が使用されます。 PyPy は、" -"おそらく、ここに ``pp18`` や ``pp19`` といったそれ自身のバージョンを使いま" -"す。" +"それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやすい " +"(例えば ``+`` は URL 内ではクォートしなければなりませんし、 ``~`` は POSIX で" +"ユーザのホームディレクトリを示すために使われます) から、あるいは、 :pep:" +"`427` で定義された wheel フォーマットを参照して作成された既存の参照実装を変更" +"すること (例えば、圧縮タグで部分部分を分割するのに ``.`` ではなく ``,`` を使" +"うようにすること) を正当化するに足りるだけのアドバンテージがないから、のいず" +"れかです。" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "誰が実装に関する短縮形のレジストリの維持管理をしているのですか？" + +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -"多くの純 Python 配布物では、バージョンは ``2`` や ``3`` や ``py2`` ・ " -"``py3`` といったメジャーバージョンだけにしておくことができます。" +"python-dev メーリングリストで要求することで、新しい２文字省略形の割り当てを受" +"けることができるでしょう。経験上は、その時点で最も卓越した４個の実装のために" +"省略形が予約されています。" -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "互換性タグは METADATA に含まれるのか、あるいは PKG-INFO か？" + +#: ../source/specifications/platform-compatibility-tags.rst:289 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -"重要なことは、 ``py2`` や ``py3`` のような major-version-only タグは " -"``py20`` や ``py30`` の短縮形であるわけではないということです。そうではなく" -"て、これらのタグは、パッケージ作成者がいくつものバージョンに互換性を持つ配布" -"物を意図的にリリースしたのです。" +"否。互換性タグはビルド済み配布物のメタデータの一部です。METADATA / PKG-INFO " +"は、その配布物の単一のビルドではなく配布物の全体にとって正当なものであるべき" +"です。" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "どうして私のお気に入りの Python 実装について言及しなかったの？" + +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -"単一ソースで Python 2/3 に互換性を持つ配布物は、合成タグ ``py2.py3`` を用いる" -"ことができます。 後述の `タグの圧縮された組み合わせ `_ " -"を参照してください。" - -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" -msgstr "ABI タグ" +"省略形タグは、コンパイル済みの Python コードを公開のインデックスでシェアする" +"ことを促進します。あなたの Python 実装においてもこの仕様を使うことができます" +"が、しかしもっと長いタグになってしまうことでしょう。すべての \"純 Python\" な" +"ビルド済み配布物が単に ``py`` を使うだけであることを思い出してください。" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/platform-compatibility-tags.rst:303 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -"ABI タグは、いずれかの拡張モジュールによってどのような Python ABI が要求され" -"ているのかを示します。実装依存の ABI 群については、実装 (の名前) は、たとえ" -"ば ``cp33d`` がデバッグオプション付きの CPython 3.3 ABI のことを指すように、 " -"Python タグと同様のやり方で短縮したものを使います。" +"どうして参照実装における ABI タグ (第２のタグ) は時々 \"none\" なのですか？" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -"CPython の安定版 ABI のことは、共有ライブラリの拡張子と同様に ``abi3`` と書き" -"ます。" +"Python 2 では SOABI (より新しい版の Python 3 から来た概念) を作成する簡単な方" +"法がないので、本稿執筆時点の参照実装は \"none\" なのです。理想的には、それは" +"もっと新しい版の Python に相似の \"py27(d|m|u)\" を検出するようになるでしょう" +"が、それまでの間は \"知られていない\" ことを示すのに \"none\" とすることが必" +"要十分な方法なのです。" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr ":file:`.pypirc` ファイル" + +#: ../source/specifications/pypirc.rst:8 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -"非常に不安定な ABI を持つ実装は、そのソースコードのリビジョンやコンパイラフラ" -"グその他の SHA-256 ハッシュ値の最初の６バイトを (BASE64にエンコードされた８文" -"字として) 用いても構いませんが、おそらくはバイナリ配布物を配布することには大" -"きな需要はないでしょう。それぞれの実装のコミュニティで ABI タグをどのように用" -"いるのが最適かを決定すればよいでしょう。" +":file:`.pypirc` ファイルを使うと、 :term:`パッケージインデックス ` (ここでは \"リポジトリ\" と呼びます) 向けの設定を定義しておけば、 :" +"ref:`twine` や :ref:`flit` でパッケージをアップロードする際に URL ・ユーザ" +"名・パスワードなどの入力を省くことができます。" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" -msgstr "プラットフォームタグ" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "(元々は :ref:`distutils` パッケージで定義された) フォーマットは:" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -"プラットフォームタグは、すべてのハイフン ``-`` とピリオド ``.`` をアンダース" -"コア ``_`` で単純に置き換えた ``sysconfig.get_platform()`` です。 :ref:" -"`distutils` が Python 3.12 で削除されるまでは、これは ``distutils.util." -"get_platform()`` でした。" +"``distutils`` の節では、リポジトリを説明するようなすべての節の名前を列挙する " +"``index-servers`` フィールドを定義しています。" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" -msgstr "win32" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" +msgstr "リポジトリを記述する各節では、３個のフィールドを定義しています:" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" -msgstr "linux_i386" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." +msgstr "``repository``: リポジトリの URL。" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" -msgstr "linux_x86_64" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "``username``: リポジトリで登録済みのユーザ名。" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" -msgstr "``manylinux``" +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." +msgstr "``password``: ユーザ名を認証するために使われるパスワード。" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -"Linux プラットフォームのエコシステムが巨大であることとそれらの間に微妙な差異" -"があることから、 :pep:`425` で定義されたスキームは、Linux プラットフォーム向" -"けの wheel ファイル (および、一般に \\*nix 向けの wheel ファイル) の公開配布" -"物としては不十分です。" +"あなたのパスワードが平文で保存されることに注意してください。より良いセキュリ" +"ティのために `キーリング `_ ・環境変数での設定・コマンドラインでのパ" +"スワード供給のような代替策を検討してください。" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:47 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -"代わりに、 :pep:`600` で Linux プラットフォームの共通のサブセットを表現する" -"``manylinux`` 標準が定義されており、普通の Linux ディストロのほとんどで使え" -"る ``manylinux`` プラットフォームタグ付きの wheel をビルドできるようにしてい" -"ます。" +"そうでなければ、 :file:`.pypirc` のパーミッションを設定して、自分だけが閲覧や" +"修正を行えるようにしてください。例えば、 Linux や macOS では次のようにします:" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" +msgstr "共通の設定" + +#: ../source/specifications/pypirc.rst:61 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -"``manylinux`` 仕様は複数回の改訂があり、それぞれの版がその時々の Linux の共通" -"のサブセットを表現しています:" +"これらの例は :ref:`twine` に当てはまります。他のプロジェクト (例えば :ref:" +"`flit`) でも :file:`.pypirc` ファイルを利用しますが、デフォルトの値が異なりま" +"す。もっと詳しい情報や使い方の指南については、それぞれのプロジェクトの説明文" +"書を参照してください。" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pypirc.rst:65 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -"``manylinux1`` (:pep:`513`) は、 ``x86_64`` および ``i686`` アーキテクチャを" -"サポートしていて、 2007 年から互換性のある Linux プラットフォームに基づいてい" -"ます。" +"Twine のデフォルト設定は、 PyPI と TestPyPI のリポジトリ節を含んだ :file:`." +"pypirc` を真似ています:" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pypirc.rst:81 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -"``manylinux2010`` (:pep:`571`) は、 ``x86_64`` および ``i686`` アーキテクチャ" -"をサポートしており、以前の仕様を更新して、その代わりに 2010 年から互換性のあ" -"る Linux プラットフォームに基づいています。" +"Twine は、 :file:`$HOME/.pypirc` からの設定に対して、コマンドラインや環境変数" +"といった追加の設定をデフォルト設定に追加するでしょう。" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" +msgstr "PyPI トークンを使う" + +#: ../source/specifications/pypirc.rst:87 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -"``manylinux2014`` (:pep:`599`) では、多数のアーキテクチャ (``aarch64``, " -"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``) へのサポートを追加し、ま" -"た、2014 年以降の互換 Linux プラットフォームのベースを更新しました。" +"自分の PyPI 用 `API トークン `_ を設定するには、次のような :file:" +"`$HOME/.pypirc` を作れば良いでしょう:" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pypirc.rst:96 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -"``manylinux_x_y`` (:pep:`600`) では、それまでの PEP 群を全て代替する形で将来" -"を見据えた標準を定義しました。 ``x`` と ``y`` は、その標準がサポートする " -"glibc のメジャーバージョンとマイナーバージョンとして定義されています (例え" -"ば、 ``manylinux_2_24`` は glibc 2.24+ を使っているディストロならどれでも、そ" -"の上で動作するはずです) 。以前に使われたタグは広報互換性を保つために依然とし" -"てサポートされています。" +":ref:`TestPyPI ` 用には、Test PyPI アカウントで作成した API" +"トークンを使った ``[testpypi]`` 節を追加してください。" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" +msgstr "別のパッケージインデックスを使う" + +#: ../source/specifications/pypirc.rst:104 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -"一般に、古めのバージョンの仕様向けにビルドされた配布物には前方互換性がありま" -"す (というのは、 ``manylinux1`` の配布物はより新しいシステムでも同様に動作す" -"るはずだということです) が、後方互換性はありません (``manylinux2010`` の配布" -"物が 2010 年よりも前に存在していたプラットフォームで動作するとは想定されてい" -"ないということです) 。" +"追加のリポジトリの設定を行うには、 ``index-servers`` フィールドにそのリポジト" +"リの名前が含まれるように再定義する必要があるでしょう。PyPI と TestPyPI とプラ" +"イベートなリポジトリの設定をした :file:`$HOME/.pypirc` の完全な例を示します:" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -"``manylinux1`` と ``manylinux2010`` は既に end-of-life に達していて、提供され" -"ているビルド環境にはもはやセキュリティアップデートが提供されることはないであ" -"ろうという警告されていることもあって、パッケージ保守者は最も互換性のある仕様" -"をターゲットにするように努力するべきです。" +"``password`` フィールドを使う代わりに、 (Twineによってインストールされる) `" +"キーリング `_ を使って API トークンやパスワードを安全に保存すること" +"を検討してください:" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" -msgstr "Manylinux 互換性サポート" +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +msgid "``pyproject.toml`` specification" +msgstr "``pyproject.toml`` は必須ですか？" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -"``manylinux2014`` 仕様は相対的に新しく、未だインストールツールに広く認識され" -"たと言える状況ではありません。" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -"``manylinux_x_y`` 仕様は相対的に新しく、未だインストールツールに広く認識され" -"たと言える状況ではありません。" -#: ../source/specifications/platform-compatibility-tags.rst:157 -msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -"適切なプロジェクトがサポートするさまざまな ``manylinux`` 標準の最低限のバー" -"ジョンを次に掲げる表に示します:" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "ツール" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" -msgstr "``manylinux1``" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" -msgstr "``manylinux2010``" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" -msgstr "``manylinux2014``" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" -msgstr "``manylinux_x_y``" - -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" -msgstr "``>=8.1.0``" - -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" -msgstr "``>=19.0``" - -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" -msgstr "``>=19.3``" - -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" -msgstr "``>=20.3``" - -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "auditwheel" - -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "``>=1.0.0``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:19 +msgid "" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" -msgstr "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:29 +#, fuzzy +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "ビルドシステムの依存関係を宣言する" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:31 +#, fuzzy +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" +"`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファイル" +"形式で、あるプロジェクトのビルドシステムが正常に動作するためにインストールさ" +"れていなければならない Python レベルの依存関係をすべて宣言するという目的のた" +"めにそのプロジェクトが提供するものです。" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:37 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -"audit wheel 3.3.0 では ``manylinux_2_24`` へのサポートだけが追加されました" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -"タグ類は、 (もしダウンロードが必要なら) 選択可能なビルド済配布物のリストの中" -"からどれをダウンロードするのかをインストーラが決定するために使われます。イン" -"ストーラは、自身がサポートする (pyver, abi, arch) タプルのリストを維持管理し" -"ています。ビルド済配布物のタグがリストに含まれて (``in`` ) いれば、それをイン" -"ストールすることができます。" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -"古い Python リリース向けに発行された純 Python のバージョンにフォールバックす" -"るよりも前に、利用できる中で最も機能を網羅したビルド済配布物 (インストールす" -"る先の環境に最も適したもの) をインストーラがデフォルトで選択することが推奨さ" -"れています。インストーラは、また、受け入れ可能な互換性タグのリストを設定変更" -"したり順序を入れ替えたりする方法を持つことが推奨されています; 例えば、ユーザ" -"は、純 Python であると広報しているビルド済みパッケージだけをダウンロードする" -"ために、 ``*-none-any`` タグだけを受容しても構いません。" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -"互換性はあるがもはや古くなってしまったビルド済みのものを使う選択肢よりもより" -"好ましいという点で、インストーラに望まれるもうひとつの機能は \"可能ならソース" -"コードから再コンパイルする\" でしょう。" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -"この事例集は、インストーラを linux_x86_64 システム上の CPython 3.3 のもとで走" -"らせるためのものです。最も好ましいもの (最新版の Python 向けにビルドされたコ" -"ンパイル済みの拡張モジュールが付属している配布物) から、最も好ましくはないも" -"の (古いバージョンの Python でビルドされた純 Python の配布物) へ、という順序" -"で並んでいます:" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" -msgstr "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:103 +#, fuzzy +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "プロジェクトのメタデータを宣言する" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" -msgstr "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" -msgstr "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" +"メタデータにはふたつの種類があります: *静的* なものと *動的* なものです。静的" +"なメタデータは ``pyproject.toml`` ファイルで直接指定されていて、ツール側では" +"指定したり変更したりできません (これは、例えばメタデータが参照するファイルの" +"内容のような、メタデータによって *参照* されるデータを含みます)。動的なメタ" +"データは ``dynamic`` キー (この仕様内で後で定義します) を経由して一覧化されて" +"いて、ツール側が後から提供することになるでしょう。" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" -msgstr "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" -msgstr "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" +msgstr "必ず静的に定義しなければならない必須のキーは次の通り:" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" -msgstr "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" +"必須フィールドだが、静的に指定しても動的に指定しても *いずれでも構わない* " +"キーは以下の通り:" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" -msgstr "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"他の全てのキーは必須ではないものと解釈され、これらは静的に指定しても動的にリ" +"ストしても未指定のままにしていても構いません。" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" -msgstr "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "``[project]`` テーブルで許容されるキーの完全なリストは次のとおりです:" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" -msgstr "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" +msgstr "``著者 ``" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" -msgstr "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" +msgstr "``依存関係 ``" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" -msgstr "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" +msgstr "``保守者 ``" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" +msgstr "``optional-dependencies``" + +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" +msgstr "TOML_ 型: 文字列" + +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -"ビルド済み配布物は、サブプロセスとして起動されるネーティブの実行可能ファイル" -"を含んでいるなどのようなC 言語拡張以外の理由によって、特定のプラットフォーム" -"向けであっても構いません。" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`名前 " +"` フィールド" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." +msgstr "プロジェクトの名前。" + +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -"時々、あるパッケージの特定のバージョンとして複数のビルド済み配布物が存在する" -"ことがあるでしょう。例えば、パッケージ製作者が、 ``cp33-abi3-linux_x86_64`` " -"というタグを付けて追加的な C 言語拡張を含むパッケージをリリースし、そのような" -"ものを含まない同じ配布物に ``py3-none-any`` というタグを付けてリリースするよ" -"うな場合です。(このような場合でも) サポートされるタグのリストで先に出現する方" -"を優先するという理由によって C 言語拡張付きのパッケージがそうでないパッケージ" -"よりも選好されてインストールされるという形で、インデックスによってどちらかに" -"決めることができます。" +"内部的な一貫性を保つために、ツール側では読み取ったらすぐに、この名前を :ref:`" +"正規化 ` するべきです。" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" -msgstr "圧縮されたタグのセット" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" +":ref:`コアとなるメタデータ ` に対応する: :ref:`バージョン " +"`" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -"bdists のコンパクトなファイル名で、互換性のあるタグトリプルが複数ある場合にも" -"きちんと動作するものを許容するためには、代わりにファイル名の中のそれぞれのタ" -"グが '.' で分割可能でありソート可能であるような一連のタグになっていることが可" -"能です。例えば、 pip は純 Python のパッケージで、同一のソースコードで Python " -"2 でも 3 でも動作するように書かれていますが、これは ``py2.py3-none-any`` とい" -"うタグを付けた bdist として配布することができるでしょう。単純なタグの完全なリ" -"ストは::" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "ユーザは正規化済みのバージョンを指定するようにするべきです。" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`要約 " +"`" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." +msgstr "プロジェクトを要約する記述。" + +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" +msgstr "TOML_ 型: 文字列またはテーブル" + +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" +"対応する `コアとなるメタデータ ` フィールド: :ref:" +"`Description ` and :ref:`Description-Content-Type " +"`" + +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." +msgstr "プロジェクトの説明全体 (すなわち README)。" + +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" +"このキーは文字列かテーブルを受け付けます。もし文字列なら、完全な説明を含むテ" +"キストファイルの位置を ``pyproject.toml`` からの相対パスで示したものです。" +"ツールの側ではこのファイルが UTF-8 でエンコードされているものと想定しなければ" +"なりません。ファイルパスが大文字小文字を問わず ``.md`` 拡張子で終わっている場" +"合は、ツールはそのファイルの content-type が ``text/markdown`` であるものと仮" +"定しなければなりません。ファイルパスが大文字小文字を問わず ``.rst`` で終わっ" +"ている場合は、ツールは content-type が ``text/x-rst`` であるものと仮定しなけ" +"ればなりません。この PEP で指定するよりも多くの拡張子をツールが認識するなら、" +"そのようなツールは、このキーを ``dynamic`` であると指定していなくても、ユーザ" +"のために content-type を推測しても構いません。content-type が与えられていない" +"場合には、全ての認識できない拡張子についてツールはエラーを発生させなければな" +"りません。" + +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" +"``readme`` キーはその値がテーブルでも構いません。 ``file`` キーは、完全な説明" +"を含むファイルへの ``pyproject.toml`` ファイルからの相対パスを表現する文字列" +"を値として持ちます。 ``text`` キーは、完全な説明そのものである文字列を値に持" +"ちます。これらのキーは排他的にいずれかひとつしか使えないので、もしメタデータ" +"がこれら両方のキーを同時に指定していたらツールはエラーを発生させなければなり" +"ません。" + +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" +"``readme`` キーに指定されたテーブルには、完全な説明の content-type を指定する" +"文字列を値とする ``content-type`` キーも含まれています。メタデータがこのキー" +"をテーブルの中で指定していない場合には、ツールはエラーを発生させなければなり" +"ません。メタデータで ``charset`` パラメータが指定されていない場合には、 " +"UTF-8 であるものと想定されます。ツールは各ツールが独自に選択した他のエンコー" +"ディングをサポートしても構いません。 :ref:`コアとなるメタデータ ` によってサポートされている content-type に変換することができるので" +"あれば、ツールはそのような代替 content-type をサポートしても構いません。そう" +"でなければ、ツールはサポートしていない content-type に対してエラーを発生させ" +"なければなりません。" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:" +"`Requires-Python `" + +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." +msgstr "プロジェクトが要求する Python のバージョン。" + +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" +msgstr "TOML_ 型: テーブル" + +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`License `" + +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." +msgstr "" +"テーブルには二つのキーのうちのいずれか一つを書くことができます。 ``file`` " +"キーは、 ``pyproject.toml`` からプロジェクトのライセンス情報を含むファイルへ" +"の相対パスを値とする文字列です。ツールの側では、そのファイルのエンコーディン" +"グが UTF-8 であるものと仮定しなければなりません。 ``text`` キーは、プロジェク" +"トのライセンス条項そのものである文字列を値に取ります。これらのキーは相互に排" +"他的で、従って、両方のキーが指定されているメタデータについてツールの側ではエ" +"ラーを発生させなければなりません。" + +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "TOML_ 型: 文字列のキー・バリュー組を伴ったインラインテーブルの配列" + +#: ../source/specifications/pyproject-toml.rst:254 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" +msgstr "" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Author ` ・ :ref:`Author-email ` ・ :ref:`Maintainer ` ・ :ref:`Maintainer-" +"email `" + +#: ../source/specifications/pyproject-toml.rst:260 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" +"プロジェクトの \"作者\" であると考えられる人々ないし組織。正確な意味はさまざ" +"まに解釈可能です — 元々のまたは主要な作者でも構わないし、現在の保守者やパッ" +"ケージのオーナでも構いません。" + +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" +"\"maintainers\" キーは \"authors\" キーに似ていて、その正確な意味はさまざまに" +"解釈可能です。" + +#: ../source/specifications/pyproject-toml.rst:268 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" +"これらのキーは、 ``name`` と ``email`` のふたつのキーを伴ったテーブルの配列を" +"受け入れます。両方の値は文字列でなければなりません。 ``name`` の値は、電子" +"メールアドレスにおける正当な名前 (すなわち、 :rfc:`822` における電子メールア" +"ドレスのアドレス部分に前置できる名前なら何でも可) で、コンマを含まないもので" +"なければなりません。 ``email`` の値は、正当な電子メールアドレスでなければなり" +"ません。これらのキーは共に必須ではありませんが、少なくともいずれかのキーが" +"テーブル内で指定されていなければなりません。" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" +"データを使って :ref:`コアとなるメタデータ ` に書き込むやり方は" +"次の通りです:" + +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" +"``name`` だけが与えられた場合には、その値を :ref:`Author ` なり :ref:`Maintainer ` なりに書き込みま" +"す。" + +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" +"``email`` だけの場合には、その値を :ref:`Author-email ` なり :ref:`Maintainer-email ` なりに" +"書き込みます。" + +#: ../source/specifications/pyproject-toml.rst:285 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" +"``email`` と ``name`` の両方が与えられた場合には、 ``{name} <{email}>`` の" +"フォーマットで :ref:`Author-email ` なり :ref:" +"`Maintainer-email ` なりに書き込みます。" + +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." +msgstr "複数の値がある場合はコンマで区切るべきです。" + +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "TOML_ 型: 文字列の配列" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -"このスキームを実装する bdist フォーマットは、拡張されたタグ群を bdist に特有" -"のメタデータの中に含んでいるべきです。この圧縮スキームは、サポートされていな" -"いタグや例えば \"cp33-cp31u-win64\" のようにいかなる Python 実装においてもサ" -"ポートされていない \"不可能な\" タグを大量に生成すると思われるので、控えめに" -"使うようにしてください。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Keywords ` field: :ref:`Classifier " +"`" msgstr "" -"ツール類は、 ``cp33-cp33m-win32`` のようなアーキテクチャへの依存を示すタグや " -"``py33-none-any`` のような純 Python タグの中で最も好ましいものをデフォルトで" -"採用するべきです。パッケージ製作者がデフォルトをオーバーライドしていたとすれ" -"ば、それは彼らが異なる Python 間での互換性を提供しようという意図があったこと" -"を示しています。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Classifier `" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." +msgstr "プロジェクトに適合する Trove 分類子。" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" +msgstr "TOML_ 型: 文字列のキー・バリューを伴うテーブル" + +#: ../source/specifications/pyproject-toml.rst:316 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -"自分の配布物が最新版の Python と相容れない機能を使っているとしたら、どんなタ" -"グを使いますか？" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Project-URL `" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -"互換性タグは、インストーラがある配布物の *単一のバージョン* の *最も互換性が" -"ある* ビルドを選択する際に助けとなります。例えば、 (Python 3.4 に特有の機能を" -"使っている) ``beaglevote-1.2.0``には Python 3.3 と互換性を持つビルドがひとつ" -"もないという場合でも、 ``py34-none-any`` タグの代わりに ``py3-none-any`` タグ" -"を使っても構いません。 Python 3.3 のユーザが互換性のあるビルドを得るために" -"は、新しい機能を使う前のリリースである ``beaglevote-1.1.0`` 用の要求 " -"(requirement) などを他の指定子を組み合わせなければなりません。" +"URL のテーブルで、 URL に付けられたラベルがキーで URL そのものが値になってい" +"るもの。" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" -msgstr "Python のバージョン番号に ``.`` がないのはなぜですか?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" +msgstr "エントリポイント" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -"CPython は、数字３個のメジャーリリースなしで 20 年以上にわたって存続してきま" -"した。これはしばらくの間は続くに違いありません。 - や . が周辺のファイル名を" -"区切る役割を果たしているので、他の実装では _ を区切り子として使っても構いませ" -"ん。" +"TOML_ 型: table (``[project.scripts]`` ・ ``[project.gui-scripts]`` ・ " +"``[project.entry-points]``)" -#: ../source/specifications/platform-compatibility-tags.rst:272 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Entry points specification `" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -"ハイフンやその他の英数字以外の文字をアンダースコアに正規化するのはなぜですか?" +"みっつのテーブルがエントリポイントに関係しています。 ``[project.scripts]`` " +"テーブルは、 :ref:`エントリポイント仕様 ` の中の " +"``console_scripts`` グループに対応しています。テーブル内のキーはエントリポイ" +"ントの名前であり、値は参照されるオブジェクトです。" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -"ファイル名の部分部分を区分けする ``.`` 文字や ``-`` 文字との干渉を避けるため" -"に、かつ、 (クォートすることなく URL パス内で使用可能であることを含む) 数多あ" -"るファイルシステムのファイル名に対する制限事項との間のより良い互換性のため" -"に。" - -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" -msgstr "何故、 ``.`` や ``-`` の代わりに特殊な文字 を使わないのですか？" +"``[project.gui-scripts]`` テーブルは、 :ref:`エントリポイント仕様 ` の中の ``gui_scripts`` グループに対応します。そのフォーマットは " +"``[project.scripts]`` と同じです。" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -"それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやすい " -"(例えば ``+`` は URL 内ではクォートしなければなりませんし、 ``~`` は POSIX で" -"ユーザのホームディレクトリを示すために使われます) から、あるいは、 :pep:" -"`427` で定義された wheel フォーマットを参照して作成された既存の参照実装を変更" -"すること (例えば、圧縮タグで部分部分を分割するのに ``.`` ではなく ``,`` を使" -"うようにすること) を正当化するに足りるだけのアドバンテージがないから、のいず" -"れかです。" - -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" -msgstr "誰が実装に関する短縮形のレジストリの維持管理をしているのですか？" +"``[project.entry-points]`` テーブルは、テーブルの集合体です。それぞれのサブ" +"テーブルの名前は、ひとつのエントリポイントグループです。キーと値の意味すると" +"ころは ``[project.scripts]`` と同じです。ユーザはネストしたサブテーブルを作っ" +"てはならず、代わりにエントリポイントグループを１段階の深さに保つようにしなけ" +"ればなりません。" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -"python-dev メーリングリストで要求することで、新しい２文字省略形の割り当てを受" -"けることができるでしょう。経験上は、その時点で最も卓越した４個の実装のために" -"省略形が予約されています。" +"メタデータの中に ``[project.entry-points.console_scripts]`` もしくは " +"``[project.entry-points.gui_scripts]`` というテーブルが定義されている場合は、" +"それぞれ ``[project.scripts]`` や ``[project.gui-scripts]`` と混同してしまう" +"といけないので、ビルド時のバックエンドがエラーを発生させなければなりません。" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" -msgstr "互換性タグは METADATA に含まれるのか、あるいは PKG-INFO か？" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" +"TOML_ 型: :pep:`508` の文字列 (``dependencies``) の配列、および、 :pep:`508` " +"の文字列 (``optional-dependencies``) の配列の値を伴ったテーブル" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -"否。互換性タグはビルド済み配布物のメタデータの一部です。METADATA / PKG-INFO " -"は、その配布物の単一のビルドではなく配布物の全体にとって正当なものであるべき" -"です。" +"対応する :ref:`コアとなるメタデータ ` フィールド: :ref:" +"`Requires-Dist ` および :ref:`Provides-Extra " +"`" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" -msgstr "どうして私のお気に入りの Python 実装について言及しなかったの？" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." +msgstr "(必須ではない) プロジェクトの依存関係。" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:365 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -"省略形タグは、コンパイル済みの Python コードを公開のインデックスでシェアする" -"ことを促進します。あなたの Python 実装においてもこの仕様を使うことができます" -"が、しかしもっと長いタグになってしまうことでしょう。すべての \"純 Python\" な" -"ビルド済み配布物が単に ``py`` を使うだけであることを思い出してください。" +"``dependencies`` には、文字列の配列が値であるようなキーです。それぞれの文字列" +"がそのプロジェクトの依存関係を表現していて、正当な :pep:`508` の文字列として" +"フォーマットされていなければなりません。それぞれの文字列は、 :ref:`Requires-" +"Dist ` エントリに直接にマップしています。" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:370 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -"どうして参照実装における ABI タグ (第２のタグ) は時々 \"none\" なのですか？" +"``optional-dependencies`` は、それぞれのキーが追加物で、その値が文字列の配列" +"であるようなテーブルです。文字列の配列は正当な :pep:`508` の文字列でなければ" +"なりません。キーは :ref:`Provides-Extra ` とし" +"てみた時に正当な値でなければなりません。従って、配列の中のそれぞれの値は、一" +"致する :ref:`Provides-Extra ` メタデータに対応" +"する :ref:`Requires-Dist ` のエントリになりま" +"す。" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" +msgstr "TOML_ 型: 文字列の配列" + +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -"Python 2 では SOABI (より新しい版の Python 3 から来た概念) を作成する簡単な方" -"法がないので、本稿執筆時点の参照実装は \"none\" なのです。理想的には、それは" -"もっと新しい版の Python に相似の \"py27(d|m|u)\" を検出するようになるでしょう" -"が、それまでの間は \"知られていない\" ことを示すのに \"none\" とすることが必" -"要十分な方法なのです。" +":ref:`コアとなるメタデータ ` フィールドに対応する: :ref:`ダイ" +"ナミック ` フィールド" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" -msgstr ":file:`.pypirc` ファイル" +#: ../source/specifications/pyproject-toml.rst:390 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" +"この PEP に列挙されたキーのどれを意図的に指定しないままにすることで他のツール" +"が動的にそのようなメタデータを準備することができる/しようとするかを規定しま" +"す。後述するツールによる設定に比較して、どのメタデータが目的を持って未指定に" +"されていて未指定のままであることを期待されているのかについて明確に描き出しま" +"す。" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -":file:`.pypirc` ファイルを使うと、 :term:`パッケージインデックス ` (ここでは \"リポジトリ\" と呼びます) 向けの設定を定義しておけば、 :" -"ref:`twine` や :ref:`flit` でパッケージをアップロードする際に URL ・ユーザ" -"名・パスワードなどの入力を省くことができます。" - -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" -msgstr "(元々は :ref:`distutils` パッケージで定義された) フォーマットは:" +"ビルド用のバックエンドは、静的に指定されたメタデータ (つまり ``dynamic`` 内に" +"列挙されたキーではないメタデータ) を尊重しなければなりません。" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -"``distutils`` の節では、リポジトリを説明するようなすべての節の名前を列挙する " -"``index-servers`` フィールドを定義しています。" - -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" -msgstr "リポジトリを記述する各節では、３個のフィールドを定義しています:" - -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." -msgstr "``repository``: リポジトリの URL。" - -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." -msgstr "``username``: リポジトリで登録済みのユーザ名。" - -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." -msgstr "``password``: ユーザ名を認証するために使われるパスワード。" +"メタデータで ``dynamic`` 内に ``name`` が指定されている場合には、ビルド用バッ" +"クエンドがエラーを発生させなければなりません。" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -"あなたのパスワードが平文で保存されることに注意してください。より良いセキュリ" -"ティのために `キーリング `_ ・環境変数での設定・コマンドラインでのパ" -"スワード供給のような代替策を検討してください。" +":ref:`コアとなるメタデータ ` の仕様において、あるキーが \"必須" +"である\" ものとして挙げられている場合には、メタデータはそのキーを静的に指定す" +"るか、または、 ``dynamic`` 内に指定するかしなければなりません (どちらでもない" +"場合にはビルドバックエンドがエラーを発生させなければなりません、すなわち、必" +"須のフィールドが ``[project]`` テーブルの中にどんな形でも存在していないという" +"ことは不可能であるべきです)。" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -"そうでなければ、 :file:`.pypirc` のパーミッションを設定して、自分だけが閲覧や" -"修正を行えるようにしてください。例えば、 Linux や macOS では次のようにします:" - -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" -msgstr "共通の設定" +":ref:`コアとなるメタデータ ` の仕様で、あるキーを \"必須ではな" +"い\" ものとして挙げている場合には、後でビルド用バックエンドがそのキー用のデー" +"タを提供するという期待が持てるのであればメタデータではそのキーを ``dynamic`` " +"の中に挙げても構いません。" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -"これらの例は :ref:`twine` に当てはまります。他のプロジェクト (例えば :ref:" -"`flit`) でも :file:`.pypirc` ファイルを利用しますが、デフォルトの値が異なりま" -"す。もっと詳しい情報や使い方の指南については、それぞれのプロジェクトの説明文" -"書を参照してください。" +"メタデータ内で、あるキーが静的に指定されていて、かつ、 ``dynamic`` にも挙げて" +"ある場合には、ビルド用バックエンドはエラーを発生させなければなりません。" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -"Twine のデフォルト設定は、 PyPI と TestPyPI のリポジトリ節を含んだ :file:`." -"pypirc` を真似ています:" +"メタデータ内で、あるキーを ``dynamic`` の中に挙げなかった場合は、ビルド用バッ" +"クエンドがユーザに代わって必要なメタデータを挿入することはできません (すなわ" +"ち、ツールがメタデータを挿入できるのは ``dynamic`` の中だけであり、かつ、ユー" +"ザがそうするようにオプトインしていなければならないということです) 。" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -"Twine は、 :file:`$HOME/.pypirc` からの設定に対して、コマンドラインや環境変数" -"といった追加の設定をデフォルト設定に追加するでしょう。" - -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" -msgstr "PyPI トークンを使う" +"あるキーが ``dynamic`` の中で指定されたメタデータで、しかし、ビルド用バックエ" +"ンドがそこに挿入するべきデータを決定することができない時は、ビルド用バックエ" +"ンドはエラーを発生させなければなりません (正確な値であると判断した場合はデー" +"タを省略することが許容されます) 。" -#: ../source/specifications/pypirc.rst:87 -msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -"自分の PyPI 用 `API トークン `_ を設定するには、次のような :file:" -"`$HOME/.pypirc` を作れば良いでしょう:" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -":ref:`TestPyPI ` 用には、Test PyPI アカウントで作成した API" -"トークンを使った ``[testpypi]`` 節を追加してください。" - -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" -msgstr "別のパッケージインデックスを使う" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -"追加のリポジトリの設定を行うには、 ``index-servers`` フィールドにそのリポジト" -"リの名前が含まれるように再定義する必要があるでしょう。PyPI と TestPyPI とプラ" -"イベートなリポジトリの設定をした :file:`$HOME/.pypirc` の完全な例を示します:" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -"``password`` フィールドを使う代わりに、 (Twineによってインストールされる) `" -"キーリング `_ を使って API トークンやパスワードを安全に保存すること" -"を検討してください:" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "インストール済みのプロジェクトを記録する" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -20319,7 +19958,7 @@ msgstr "" "かに関わりなく、ツールがプロジェクトについて問い合わせを行い、管理し、あるい" "はアンインストールすることが可能になります。" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -20334,11 +19973,11 @@ msgstr "" "は提供できない場合でさえも、インストール済みのプロジェクトの名前とバージョン" "を記録するべきです。" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "ワークフローの履歴と変更" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -20356,7 +19995,7 @@ msgstr "" "するであろう機能面での変更提案は、 PEP のプロセス (:pep:`1` を見てください) " "を通じて行わなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " @@ -20366,7 +20005,7 @@ msgstr "" "理論的根拠や後方互換性を保つための考慮点のような追加的な情報を含んでいても構" "いません。" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " @@ -20376,17 +20015,8 @@ msgstr "" "ト可能なモジュールやパッケージの隣に位置する \"``.dist-info``\" ディレクトリ" "もインストールします (通常は ``site-packages`` ディレクトリ) 。" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 #, fuzzy -#| msgid "" -#| "This directory is named as ``{name}-{version}.dist-info``, with ``name`` " -#| "and ``version`` fields corresponding to :ref:`core-metadata`. Both fields " -#| "must be normalized (see :ref:`name-normalization` and :pep:`PEP 440 " -#| "<440#normalization>` for the definition of normalization for each field " -#| "respectively), and replace dash (``-``) characters with underscore " -#| "(``_``) characters, so the ``.dist-info`` directory always has exactly " -#| "one dash (``-``) character in its stem, separating the ``name`` and " -#| "``version`` fields." msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -20406,7 +20036,7 @@ msgstr "" "ひとつだけのダッシュ (``-``) 文字をそのファイル名基幹部に持ち、それによって " "``name`` と ``version`` フィールドを分割していなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -20425,7 +20055,7 @@ msgstr "" "と ``version`` の両方のフィールドを上記の規則に従って正規化しなければならず、" "既存のツールもこれらのフィールドの正規化を始めることが推奨されています。" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -20445,7 +20075,7 @@ msgstr "" "イブラリは、配布物の情報を表示する時にツールが正規化されていない名前にアクセ" "スできるように、そのようなツール群が利用できるような API を提供するべきです。" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" @@ -20453,31 +20083,31 @@ msgstr "" "この ``.dist-info`` ディレクトリには、以下に詳細を述べるこれらのファイルを置" "くことができます:" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "``METADATA``: プロジェクトのメタデータを含みます" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "``RECORD``: インストールされるファイルを列挙して記録します。" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" "``INSTALLER``: プロジェクトをインストールするのに使われるツールの名前を記録し" "ます。" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" "``entry_points.txt``: 詳細については :ref:`entry-points` を見てください" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "``direct_url.json``: 詳細については :ref:`direct-url` を見てください" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " @@ -20487,7 +20117,7 @@ msgstr "" "ルの最良で省略可能です。インストーラ独自のファイルが他に存在しても構いませ" "ん。" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -20499,7 +20129,7 @@ msgstr "" "ようなファイルをインストールされたプロジェクトの ``.dist-info`` ディレクトリ" "にコピーしても構いません。" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -20511,11 +20141,11 @@ msgstr "" "標準化されるかもしれません。その元々の意味するところについては、 `PEP 376 " "`_ を見てください。" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "METADATA ファイル" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." @@ -20523,7 +20153,7 @@ msgstr "" "``METADATA`` ファイルには、 :ref:`コアとなるメタデータ ` 仕様" "のバージョン 1.1 またはそれ以降で記述されているようなメタデータを含みます。" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " @@ -20533,11 +20163,11 @@ msgstr "" "合や、必須のコアとなるメタデータが入手できない場合には、インストーラはエラー" "を発生させてプロジェクトのインストールを失敗させなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "RECORD ファイル" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." @@ -20545,7 +20175,7 @@ msgstr "" "``RECORD`` ファイルには、インストールされたファイル群を列挙します。CSV ファイ" "ルで、インストールされたファイルを１行に一つずつ書き込みます。" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" @@ -20553,19 +20183,19 @@ msgstr "" "CSV の亜種としては、 Python の ``csv`` モジュールの ``reader`` で読めるもので" "なければなりません:" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "フィールド区切り文字: ``,`` (コンマ)、" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "引用符: ``\"`` (ストレートダブルクォート)、" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "行末文字: ``\\r\\n`` か ``\\n`` のいずれか一方。" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." @@ -20573,7 +20203,7 @@ msgstr "" "各レコードは３個の要素から構成されます: ファイルの **パス** 、内容の **ハッ" "シュ値** 、そして、その **サイズ** です。" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -20585,7 +20215,7 @@ msgstr "" "Windows では、ディレクトリはスラッシュで区切ってもバックスラッシュで区切って" "も構いません (``/`` または ``\\``) 。" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -20598,7 +20228,7 @@ msgstr "" "urlsafe_b64encode(digest)`` の結果から末尾の ``=`` を取り除いたもの) で記した" "ものです。" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." @@ -20606,7 +20236,7 @@ msgstr "" "*size* は、空文字列か、または、ファイルサイズを 10 進数のバイト数で書いたもの" "です。" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -20620,7 +20250,7 @@ msgstr "" "なっています。その他のファイルについては、インストールされたプロジェクトに関" "する完全性を検証するために情報を与えておくことが推奨されています。" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -20635,7 +20265,7 @@ msgstr "" "ル自身を含む) については、書いておかなければなりません。ディレクトリについて" "は記入してはなりません。" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " @@ -20646,11 +20276,11 @@ msgstr "" "``.pyc`` ファイルと、アンインストールによって空になったすべてのディレクトリを" "削除する必要があります。" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "ありうる ``RECORD`` ファイルの一部を切り出した例をここに掲げます::" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -20662,7 +20292,7 @@ msgstr "" "トロにおけるシステムのパッケージ管理機構のような、それ以外の情報源に依存する" "ツールには適用されません。)" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -20672,11 +20302,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "INSTALLER ファイル" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -20688,16 +20318,16 @@ msgstr "" "動されるなら、 ``INSTALLER`` はそのコマンドの名前を含んでいるべきです。そうで" "なければ印刷可能な ASCII 文字を含んでいるべきです。" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" "ファイルは、0個またはそれ以上の ASCII 空白文字で終端することができます。" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "``INSTALLER`` ファイルについて、二つの可能な例を示します::" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -20709,11 +20339,11 @@ msgstr "" "場合には、そのツールは ``INSTALLER`` ファイルに書いてある (別の) ツールを使え" "ばアンインストールができるかもしれないと示唆しても構いません。" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "entry_points.txt ファイル" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -20725,15 +20355,15 @@ msgstr "" "りすることを意図したコンポーネントを当該パッケージが含んでいる場合には、イン" "ストーラがその由を表示するためにこのファイルを作っても構いません。" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "その詳細な仕様は :ref:`entry-points` にあります。" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "direct_url.json ファイル" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." @@ -20741,15 +20371,15 @@ msgstr "" "このファイルは、要求事項が指定するダイレクト URL (VCS の URL を含む) から配布" "物をインストールする際に、インストーラによって生成されなければなりません。" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "その詳細な仕様は :ref:`direct-url` にあります。" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "インストール済みのパッケージ群への変更を意図的に防ぐ" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -20763,12 +20393,12 @@ msgstr "" "いないことを、もしそんなことをしていればより広範な環境に互換性問題を引き起こ" "しかねないので、しっかりと確認することが望ましいです。" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" "これを達成するために、影響を被るツール群は次のような段階を踏むべきです:" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -20781,7 +20411,7 @@ msgstr "" "は、パッケージの内容物を他の手段で追跡・管理しているのであればファイルを完全" "に除外しておくこと) してください。" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " @@ -20792,7 +20422,7 @@ msgstr "" "るツール群が影響を被るパッケージを修正するように言われた時により良いエラー通" "知を提供できます)" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -20805,7 +20435,7 @@ msgstr "" "別の場所を使うようにすることで、プラットフォームが提供するパッケージ群を意図" "せずに修正してしまうことを防いでも構いません。" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -20826,7 +20456,6 @@ msgstr "パッケージ配布物のメタデータ" #: ../source/specifications/section-installation-metadata.rst:3 #, fuzzy -#| msgid "Package Installation Environment Metadata" msgid "Package Installation Metadata" msgstr "パッケージのインストール環境のメタデータ" @@ -20959,10 +20588,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:45 #, fuzzy -#| msgid "" -#| "Code that produces a source distribution file MUST give the file a name " -#| "that matches this specification. This includes the ``build_sdist`` hook " -#| "of a build backend." msgid "" "Code that produces a source distribution file MUST give the file a name that " "matches this specification. This includes the ``build_sdist`` hook of a :" @@ -20990,15 +20615,16 @@ msgid "Source distribution file format" msgstr "ソースコード配布物のファイルフォーマット" #: ../source/specifications/source-distribution-format.rst:57 +#, fuzzy msgid "" "A ``.tar.gz`` source distribution (sdist) contains a single top-level " "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" "``.tar.gz`` ソースコード配布物 (sdist) には、 ``{name}-{version}`` (例えば " "``foo-1.0``) と言う名前の単一のトップレベルディレクトリがあって、そこにパッ" @@ -21228,24 +20854,23 @@ msgstr "2020-11: :pep:`643` をこの仕様に変換" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "2000-12: ソースコード配布物について :pep:`643` で標準化" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy -#| msgid "Specifications" msgid "Definitions" msgstr "仕様型文書" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -21253,7 +20878,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -21261,19 +20886,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -21281,26 +20906,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy -#| msgid "Versions" msgid "Version scheme" msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -21308,28 +20932,27 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy -#| msgid "Local version identifiers" msgid "Public version identifiers" msgstr "ローカルのバージョン指定子" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -21337,7 +20960,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -21345,63 +20968,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -21409,11 +21032,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -21422,7 +21045,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -21432,7 +21055,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -21441,7 +21064,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -21449,25 +21072,24 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 #, fuzzy -#| msgid "Start & end with an ASCII letter or digit." msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "先頭と最後の文字がASCII文字ないし数字であること。" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -21481,7 +21103,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -21489,7 +21111,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -21501,38 +21123,37 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 #, fuzzy -#| msgid "Publishing releases" msgid "Final releases" msgstr "リリースを公開する" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -21540,21 +21161,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "例えば::" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -21562,37 +21187,36 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-releases" msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -21600,50 +21224,49 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy -#| msgid "zest.releaser" msgid "Post-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -21651,7 +21274,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -21659,11 +21282,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -21671,11 +21294,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -21683,20 +21306,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -21705,13 +21328,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -21721,30 +21344,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy -#| msgid "Versions" msgid "Version epochs" msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -21755,14 +21377,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -21770,24 +21392,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy -#| msgid "Normalization" msgid "Integer Normalization" msgstr "正規化" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -21796,13 +21417,12 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release separators" msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -21812,13 +21432,12 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release spelling" msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -21828,11 +21447,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -21840,11 +21459,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -21855,13 +21474,12 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 #, fuzzy -#| msgid "Pre-release versioning" msgid "Post release spelling" msgstr "リリース前のバージョン付与方式" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -21869,11 +21487,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -21881,11 +21499,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -21895,11 +21513,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -21907,11 +21525,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -21919,13 +21537,12 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 #, fuzzy -#| msgid "Local version identifiers" msgid "Local version segments" msgstr "ローカルのバージョン指定子" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -21933,11 +21550,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -21946,11 +21563,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -21959,13 +21576,12 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 #, fuzzy -#| msgid "Here are some examples of compliant version numbers::" msgid "Examples of compliant version schemes" msgstr "規定に合致したバージョン番号の例を次に示す::" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -21975,7 +21591,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -21983,71 +21599,70 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 #, fuzzy -#| msgid "Serial versioning" msgid "Simple \"major.minor\" versioning::" msgstr "一連番号によるバージョン付与" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -22055,48 +21670,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -22107,7 +21722,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -22117,19 +21732,18 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 #, fuzzy -#| msgid "Dealing with the universal wheels" msgid "Compatibility with other version schemes" msgstr "universal wheelsの取り扱い" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -22138,20 +21752,19 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 #, fuzzy -#| msgid "Serial versioning" msgid "Semantic versioning" msgstr "一連番号によるバージョン付与" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -22162,7 +21775,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -22170,32 +21783,31 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 #, fuzzy -#| msgid "Date based versioning" msgid "DVCS based version labels" msgstr "日付ベースのバージョン付与" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -22203,32 +21815,31 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 #, fuzzy -#| msgid "Date based versioning" msgid "Olson database versioning" msgstr "日付ベースのバージョン付与" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -22236,60 +21847,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -22298,83 +21909,81 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 #, fuzzy -#| msgid "This means that the following names are all equivalent:" msgid "For example, the following groups of version clauses are equivalent::" msgstr "次に挙げる名前はすべて同等ということになります:" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy -#| msgid "Version Specifier" msgid "Version matching" msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -22383,7 +21992,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -22391,31 +22000,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -22423,7 +22032,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -22432,7 +22041,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -22442,14 +22051,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -22458,30 +22067,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy -#| msgid "Version Specifier" msgid "Version exclusion" msgstr "バージョン指定子" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -22490,27 +22098,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -22520,7 +22128,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -22530,13 +22138,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=``. It is RECOMMENDED that only hashes which " -#| "are unconditionally provided by the latest version of the standard " -#| "library's ``hashlib`` module be used for source archive hashes. At time " -#| "of writing, that list consists of 'md5', 'sha1', 'sha224', 'sha256', " -#| "'sha384', and 'sha512'." msgid "" "It is RECOMMENDED that only hashes which are unconditionally provided by the " "latest version of the standard library's ``hashlib`` module be used for " @@ -22756,14 +22355,14 @@ msgstr "" "して使うことを推奨します。本文書の執筆時点では、 'md5' ・ 'sha1' ・ 'sha224' " "・ 'sha256' ・ 'sha384' ・ 'sha512' が該当します。" -#: ../source/specifications/version-specifiers.rst:1119 +#: ../source/specifications/version-specifiers.rst:1121 msgid "" "For source archive and wheel references, an expected hash value may be " "specified by including a ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -22772,7 +22371,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -22780,7 +22379,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -22791,19 +22390,17 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy -#| msgid "For example::" msgid "Remote URL examples::" msgstr "例えば::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 #, fuzzy -#| msgid "Archive URLs" msgid "File URLs" msgstr "アーカイブ URL 群" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -22811,7 +22408,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -22819,7 +22416,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -22831,43 +22428,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -22876,20 +22473,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -23021,7 +22618,6 @@ msgstr "" #: ../source/tutorials/creating-documentation.rst:4 #, fuzzy -#| msgid "Creating Documentation" msgid "Creating documentation" msgstr "説明文書を作成する" @@ -23402,10 +22998,6 @@ msgstr "" #: ../source/tutorials/installing-packages.rst:276 #, fuzzy -#| msgid "" -#| "In both of the above cases, Windows users should _not_ use the :command:" -#| "`source` command, but should rather run the :command:`activate` script " -#| "directly from the command shell like so:" msgid "" "In both of the above cases, Windows users should *not* use the :command:" "`source` command, but should rather run the :command:`activate` script " @@ -23448,14 +23040,6 @@ msgstr "PyPI からインストールする" #: ../source/tutorials/installing-packages.rst:303 #, fuzzy -#| msgid "" -#| "The most common usage of :ref:`pip` is to install from the :term:`Python " -#| "Package Index ` using a :term:`requirement " -#| "specifier `. Generally speaking, a requirement " -#| "specifier is composed of a project name followed by an optional :term:" -#| "`version specifier `. :pep:`440` contains a :pep:" -#| "`full specification <440#version-specifiers>` of the currently supported " -#| "specifiers. Below are some examples." msgid "" "The most common usage of :ref:`pip` is to install from the :term:`Python " "Package Index ` using a :term:`requirement " @@ -23489,9 +23073,6 @@ msgstr "" #: ../source/tutorials/installing-packages.rst:354 #, fuzzy -#| msgid "" -#| "To install a version that's :pep:`\"compatible\" <440#compatible-" -#| "release>` with a certain version: [4]_" msgid "" "To install a version that's :ref:`compatible ` with a certain version: [4]_" @@ -23647,7 +23228,7 @@ msgstr "" #: ../source/tutorials/installing-packages.rst:482 msgid "Installing from VCS" -msgstr "VCS からいんすとーるする" +msgstr "VCS からインストールする" #: ../source/tutorials/installing-packages.rst:484 msgid "" @@ -24118,9 +23699,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:57 #, fuzzy -#| msgid "" -#| ":file:`__init__.py` is required to import the directory as a package, and " -#| "should be empty." msgid "" ":file:`__init__.py` is recommended to import the directory as a regular " "package, even if as is our case for this tutorial that file is empty " @@ -24199,15 +23777,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:120 #, fuzzy -#| msgid "" -#| ":file:`pyproject.toml` tells \"frontend\" build tools like :ref:`pip` " -#| "and :ref:`build` what \"backend\" tool to use to create :term:" -#| "`distribution packages ` for your project. You can " -#| "choose from a number of backends; this tutorial uses :ref:`Hatchling " -#| "` by default, but it will work identically with :ref:" -#| "`setuptools`, :ref:`Flit `, :ref:`PDM `, and others that " -#| "support the ``[project]`` table for :ref:`metadata `." msgid "" "You can choose from a number of backends; this tutorial uses :ref:`Hatchling " "` by default, but it will work identically with :ref:`setuptools`, :" @@ -24255,9 +23824,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:177 #, fuzzy -#| msgid "" -#| "``build-backend`` is the name of the Python object that frontends will " -#| "use to perform the build." msgid "" "The ``build-backend`` key is the name of the Python object that frontends " "will use to perform the build." @@ -24315,11 +23881,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:227 #, fuzzy -#| msgid "" -#| "``version`` is the package version. See the :ref:`version specifier " -#| "specification ` for more details on versions. Some " -#| "build backends allow it to be specified another way, such as from a file " -#| "or a git tag." msgid "" "``version`` is the package version. (Some build backends allow it to be " "specified another way, such as from a file or Git tag.)" @@ -24345,12 +23906,6 @@ msgstr "``description`` は、１文で短くパッケージを説明するも #: ../source/tutorials/packaging-projects.rst:233 #, fuzzy -#| msgid "" -#| "``readme`` is a path to a file containing a detailed description of the " -#| "package. This is shown on the package detail page on PyPI. In this case, " -#| "the description is loaded from :file:`README.md` (which is a common " -#| "pattern). There also is a more advanced table form described in the :ref:" -#| "`project metadata specification `." msgid "" "``readme`` is a path to a file containing a detailed description of the " "package. This is shown on the package detail page on PyPI. In this case, the " @@ -24366,10 +23921,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:238 #, fuzzy -#| msgid "" -#| "``requires-python`` gives the versions of Python supported by your " -#| "project. Installers like :ref:`pip` will look back through older versions " -#| "of packages until it finds one that has a matching Python version." msgid "" "``requires-python`` gives the versions of Python supported by your project. " "An installer like :ref:`pip` will look back through older versions of " @@ -24408,12 +23959,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:251 #, fuzzy -#| msgid "" -#| "See the :ref:`project metadata specification ` for details on these and other fields that can be defined in " -#| "the ``[project]`` table. Other common fields are ``keywords`` to improve " -#| "discoverability and the ``dependencies`` that are required to install " -#| "your package." msgid "" "See the :ref:`pyproject.toml guide ` for details on " "these and other fields that can be defined in the ``[project]`` table. Other " @@ -24760,7 +24305,21 @@ msgstr "" "ここまで読み進めてきて、もっと Python でのパッケージングについて読みたいので" "あれば、次のようなものがあります:" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:536 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:539 msgid "" "Consider packaging tools that provide a single command-line interface for " "project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" @@ -24770,23 +24329,11 @@ msgstr "" "マンドラインインタフェースでプロジェクト管理もパッケージングもできるパッケー" "ジングツールについて検討しましょう。" -#: ../source/tutorials/packaging-projects.rst:538 -msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." -msgstr "" -"ビルドツールの設定に関する背景情報や詳細情報については、 :pep:`517` や :pep:" -"`518` を読みましょう。" - -#: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr ":doc:`/guides/packaging-binary-extensions` について読みましょう。" - -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "これは、あなたのプロジェクトが :term:`PyPI ` " +#~ "でどこに並べられるかを決めるプロジェクトの名前です。 :pep:`508` に従えば、" +#~ "正当なプロジェクト名は以下の条件を満たさなければなりません：" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "先頭と最後の文字がASCII文字ないし数字であること。" + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "これはあなたのプロジェクトの現在のバージョンで、これがあることであなたのプ" +#~ "ロジェクトのユーザたちが自分が最新版を使っているのかどうかを判断したり、彼" +#~ "ら自身のソフトウェアと組み合わせて試験を行ったバージョンがどれなのかを示し" +#~ "たりすることができるようになります。" + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "バージョンは、あなたが自分のプロジェクトをリリースする度に :term:`PyPI " +#~ "` 上に表示されます。" + +#~ msgid "" +#~ "If the project code itself needs run-time access to the version, the " +#~ "simplest way is to keep the version in both :file:`setup.py` and your " +#~ "code. If you'd rather not duplicate the value, there are a few ways to " +#~ "manage this. See the \":ref:`Single sourcing the version`\" Advanced " +#~ "Topics section." +#~ msgstr "" +#~ "プログラムが動作している間に自分自身のバージョンを知る必要があるのであれ" +#~ "ば、バージョン番号を :file:`setup.py` とあなたのソースコードの両方に格納し" +#~ "ておくのがもっとも単純な方法です。値を複数箇所に書きたくないのであれば、や" +#~ "り方が2,3種類あります。「 :ref:`バージョンを一箇所で管理するには ` 」の「高度な話題」の節を見て下さい。" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "あなたのプロジェクトについて、短い説明と長い説明を与えて下さい。" + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "これらの値は、あなたのプロジェクトを公開したときに :term:`PyPI ` に表示されます。 ``pypi.org`` のユーザインタフェイ" +#~ "スでは、灰色のバナーに ``description`` を表示し、「プロジェクトの説明」と" +#~ "名付けられたセクションに ``long_description`` を表示します。" + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description`` は、プロジェクト一覧にも表示されます。例えば、https://" +#~ "pypi.org/search/?q=jupyter のような検索結果のページや、フロントページの流" +#~ "行プロジェクトや新規リリースプロジェクトの一覧や、あなたのアカウントのプロ" +#~ "ファイルページ(例えば https://pypi.org/user/jaraco/)の中のあなたがメンテナ" +#~ "ンスしているプロジェクトの一覧に表示されるということです。" + +#~ msgid "" +#~ "A :ref:`content type ` can be " +#~ "specified with the ``long_description_content_type`` argument, which can " +#~ "be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, " +#~ "corresponding to no formatting, `reStructuredText (reST) `_, and the GitHub-flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ ":ref:`content type ` は、書式のな" +#~ "い ``text/plain`` か `reStructuredText (reST) `_ の " +#~ "``text/x-rst`` か `Markdown `_ の GitHub 方言のマークダウンである ``text/markdown`` のうちのいずれか" +#~ "ひとつの書式で、 ``long_description_content_type`` 引数とともに指定するこ" +#~ "とができます。" + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "あなたのプロジェクトのホームページのURLを与えてください。" + +#~ msgid "Provide details about the author." +#~ msgstr "著者について詳しい情報を提供してください。" + +#~ msgid "" +#~ "The ``license`` argument doesn't have to indicate the license under which " +#~ "your package is being released, although you may optionally do so if you " +#~ "want. If you're using a standard, well-known license, then your main " +#~ "indication can and should be via the ``classifiers`` argument. " +#~ "Classifiers exist for all major open-source licenses." +#~ msgstr "" +#~ "``license`` 引数には、あなたのパッケージがどのライセンスの下で公開されたか" +#~ "を示すこともできますが、これは必須ではなくオプションです。あなたが一般的で" +#~ "よく知られたライセンスを採用するのであれば、 ``分類詞 `` を指" +#~ "定するだけで済ませることができると同時に済ませるべきです。メジャーなオープ" +#~ "ンソースライセンスであればどれでも、それを指し示す分類詞が用意されていま" +#~ "す。" + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "あなたのプロジェクトを特徴付ける分類詞(classifier)を設定してください。" +#~ "https://pypi.org/classifiers に全部の一覧が出ています。" + +#~ msgid "List keywords that describe your project." +#~ msgstr "あなたのプロジェクトを説明するキーワードを列挙してください。" + +#~ msgid "" +#~ "List additional relevant URLs about your project. This is the place to " +#~ "link to bug trackers, source repositories, or where to support package " +#~ "development. The string of the key is the exact text that will be " +#~ "displayed on PyPI." +#~ msgstr "" +#~ "あなたのプロジェクトに関係する追加的なURLを列挙してください。これは、バグ" +#~ "追跡システムやソースコードリポジトリ、あるいは、パッケージ開発をサポートす" +#~ "る場所などをリンクするための場所です。キー文字列をそのままテキストとして" +#~ "PyPI上に表示されます。" + +#~ msgid "" +#~ "If your project only runs on certain Python versions, setting the " +#~ "``python_requires`` argument to the appropriate :pep:`440` version " +#~ "specifier string will prevent :ref:`pip` from installing the project on " +#~ "other Python versions. For example, if your package is for Python 3+ " +#~ "only, write::" +#~ msgstr "" +#~ "あなたのプロジェクトが特定のバージョンのPythonでないと動作しないのであれ" +#~ "ば、適切な :pep:`440` バージョン特定文字列で ``python_requires`` 引数を設" +#~ "定しておくことで :ref:`pip` が他のバージョンの `Python` なのに当該プロジェ" +#~ "クトをインストールしてしまうことがなくなります。例えば、あなたのパッケージ" +#~ "が Python 3+ 向けのものであれば、このように書いてください：" + +#~ msgid "" +#~ "If your package is for Python 2.6, 2.7, and all versions of Python 3 " +#~ "starting with 3.3, write::" +#~ msgstr "" +#~ "Python 2.6と2.7、そして3.3以上のPython 3用であればこのように書きます::" + +#~ msgid "And so on." +#~ msgstr "等々。" + +#~ msgid "" +#~ "Support for this feature is relatively recent. Your project's source " +#~ "distributions and wheels (see :ref:`Packaging Your Project`) must be " +#~ "built using at least version 24.2.0 of :ref:`setuptools` in order for the " +#~ "``python_requires`` argument to be recognized and the appropriate " +#~ "metadata generated." +#~ msgstr "" +#~ "この機能がサポートされたのは比較的最近のことです。 ``python_requires`` 引" +#~ "数が認識されて適切なメタデータが生成されるためには、あなたのプロジェクトの" +#~ "ソースコード配布物やwheels (:ref:`あなたのプロジェクトをパッケージする " +#~ "` 参照)を24.2.0かそれ以降のバージョンの :ref:" +#~ "`setuptools` でビルドしなければなりません。" + +#~ msgid "" +#~ "In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " +#~ "``python_requires`` metadata. Users with earlier versions of pip will be " +#~ "able to download & install projects on any Python version regardless of " +#~ "the projects' ``python_requires`` values." +#~ msgstr "" +#~ "さらに、 :ref:`pip` のバージョン9.0.0かそれ以降のものでなければ " +#~ "``python_requires`` のメタデータを認識しません。これより前のバージョンの" +#~ "pipを使っている場合は、 ``python_requires`` の設定に関わりなくどんなバー" +#~ "ジョンのPythonを使っていてもダウンロードやインストールが可能です。" + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "Use this keyword to specify any plugins that your project provides for " +#~ "any named entry points that may be defined by your project or others that " +#~ "you depend on." +#~ msgstr "" +#~ "あなたのプロジェクト内か依存先のプロジェクトで定義された名前付きのエント" +#~ "リーポイントをあなたのプロジェクトが提供しているようなプラグインがあればこ" +#~ "のキーワード引数を使って指定してください。" + +#~ msgid "" +#~ "For more information, see the section on :ref:`Advertising Behavior " +#~ "` from the :ref:" +#~ "`setuptools` docs." +#~ msgstr "" +#~ "詳しくは、:ref:`setup tools` 文書の :ref:`広報する動作 ` の節を見てください。" + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "" +#~ "よくあるエントリーポイントとしては、\"console_scipts\" (後述)が挙げられま" +#~ "す。" + +#~ msgid "" +#~ "Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can " +#~ "then let the toolchain handle the work of turning these interfaces into " +#~ "actual scripts [2]_. The scripts will be generated during the install of " +#~ "your :term:`distribution `." +#~ msgstr "" +#~ "``console_script`` :ref:`エントリーポイント ` は、スクリプトインターフェイスを登録するために" +#~ "使ってください。そうすれば、ツールチェーンがそのようなインターフェイスを実" +#~ "際のスクリプトに変換する作業を肩代わりしてくれます[2]_ 。あなたの :term:`" +#~ "配布物 ` をインストールする途中でスクリプトが生成さ" +#~ "れます。" + +#~ msgid "" +#~ "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." +#~ msgstr "" +#~ "詳しくは、 :doc:`setuptools 説明文書 ` の中の :doc:`エン" +#~ "トリポイント ` を見てください。" + +#~ msgid "" +#~ "Specifically, the \"console_script\" approach generates ``.exe`` files on " +#~ "Windows, which are necessary because the OS special-cases ``.exe`` files. " +#~ "Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher " +#~ "for Windows <397>` allow scripts to be used in many cases, but not all." +#~ msgstr "" +#~ "特に、\"console_script\" を使うと Windows では ``.exe`` ファイルを生成しま" +#~ "すが、これはOSが特別なケースとして ``.exe`` ファイルを必要とするからで" +#~ "す。 ``PATHEXT`` や :pep:`Windows向けPythonランチャー <397>` のようなスク" +#~ "リプトを実行する機能によって多くの場合にスクリプトが使われますが、しかし、" +#~ "いつでも使えるわけではありません。" + +#~ msgid "" +#~ "The binary distribution format (:term:`wheel `) was originally " +#~ "defined in :pep:`427`. The current version of the specification is here." +#~ msgstr "" +#~ "バイナリ配布物のフォーマット (:term:`wheel `) は、元々は :pep:" +#~ "`427` で定義されました。仕様の現在のバージョンはここにあります。" + +#~ msgid "Abstract" +#~ msgstr "要約" + +#~ msgid "" +#~ "This PEP describes a built-package format for Python called \"wheel\"." +#~ msgstr "" +#~ "この PEP は、 Python 向けコンパイル済みパッケージの \"wheel\" と呼ばれる" +#~ "フォーマットについて記述しています。" + +#~ msgid "PEP Acceptance" +#~ msgstr "PEP の受諾" + +#~ msgid "" +#~ "This PEP was accepted, and the defined wheel version updated to 1.0, by " +#~ "Nick Coghlan on 16th February, 2013 [1]_" +#~ msgstr "" +#~ "この PEP は受諾され、定義された wheel のバージョンが 1.0 に2013年2月16日" +#~ "に Nick Coghlan によって更新されました" + +#~ msgid "Rationale" +#~ msgstr "理論的根拠" + +#~ msgid "" +#~ "Python needs a package format that is easier to install than sdist. " +#~ "Python's sdist packages are defined by and require the distutils and " +#~ "setuptools build systems, running arbitrary code to build-and-install, " +#~ "and re-compile, code just so it can be installed into a new virtualenv. " +#~ "This system of conflating build-install is slow, hard to maintain, and " +#~ "hinders innovation in both build systems and installers." +#~ msgstr "" +#~ "Python には sdist よりも簡単にインストールすることができるパッケージフォー" +#~ "マットが必要です。 Python の sdist パッケージは、ソースコードをビルドした" +#~ "りインストールしたり再コンパイルしたりするために任意のコードを実行し、そう" +#~ "することで新しい virtualenv 環境にインストールできるように、 distutiles " +#~ "と setuptools によるビルドシステムによって定義され、かつ、これらのツールを" +#~ "必要とします。このようなビルドとインストールを合成したシステムは動作が遅" +#~ "く、維持管理が困難であり、ビルドシステムとインストーラの双方における技術革" +#~ "新を阻害します。" + +#~ msgid "" +#~ "Wheel attempts to remedy these problems by providing a simpler interface " +#~ "between the build system and the installer. The wheel binary package " +#~ "format frees installers from having to know about the build system, saves " +#~ "time by amortizing compile time over many installations, and removes the " +#~ "need to install a build system in the target environment." +#~ msgstr "" +#~ "Wheel は、ビルドシステムとインストーラの間により単純なインタフェイスを提供" +#~ "することで、これらの問題を癒すことを試みます。 wheel バイナリパッケージの" +#~ "フォーマットは、インストーラがビルドシステムについて知らなくても済むように" +#~ "し、何度もインストールするとしてもコンパイルにかかる時間を節約できるように" +#~ "し、また、インストール先の環境にビルドシステムをインストールする必要を取り" +#~ "除きます。" + +#~ msgid "Comparison to .egg" +#~ msgstr ".egg との比較" + +#~ msgid "" +#~ "Wheel is an installation format; egg is importable. Wheel archives do " +#~ "not need to include .pyc and are less tied to a specific Python version " +#~ "or implementation. Wheel can install (pure Python) packages built with " +#~ "previous versions of Python so you don't always have to wait for the " +#~ "packager to catch up." +#~ msgstr "" +#~ "Wheel はインストールするためのフォーマットのひとつですが、 egg はインポー" +#~ "トすることができます。 Wheel アーカイブには .pyc が含まれている必要がない" +#~ "ので、 Python の特定のバージョンや実装に紐づく度合いがより小さくなりま" +#~ "す。 Wheel は、以前のバージョンの Python でビルドされた (純 Python の) " +#~ "パッケージをインストールすることができるので、必ずしもパッケージ制作者が追" +#~ "いつくのを待つ必要がありません。" + +#~ msgid "" +#~ "Wheel uses .dist-info directories; egg uses .egg-info. Wheel is " +#~ "compatible with the new world of Python packaging and the new concepts it " +#~ "brings." +#~ msgstr "" +#~ "Wheel は .dist-info ディレクトリを使用するが、 egg は .egg-info を使いま" +#~ "す。 Wheel は、 Python のパッケージングにおける新しい世界とそれがもたらす" +#~ "新しい概念に適合しています。" + +#~ msgid "" +#~ "Wheel has a richer file naming convention for today's multi-" +#~ "implementation world. A single wheel archive can indicate its " +#~ "compatibility with a number of Python language versions and " +#~ "implementations, ABIs, and system architectures. Historically the ABI " +#~ "has been specific to a CPython release, wheel is ready for the stable ABI." +#~ msgstr "" +#~ "Wheel は、今日の複数実装世界に合わせて、より表現力が高いファイル命名慣習を" +#~ "持っています。単独の wheel アーカイブ (訳注、その名前) が、数々の Python " +#~ "言語のバージョンや実装、ABI やシステムアーキテクチャとの互換性を表示するこ" +#~ "とができるのです。歴史的には、 ABI は CPython のリリースに紐づいていました" +#~ "が、 wheel は安定な ABI に対応しています。" + +#~ msgid "" +#~ "Wheel is lossless. The first wheel implementation bdist_wheel always " +#~ "generates egg-info, and then converts it to a .whl. It is also possible " +#~ "to convert existing eggs and bdist_wininst distributions." +#~ msgstr "" +#~ "Wheel はロスレスです。最初の wheel 実装である bdist_wheel は常に egg-info " +#~ "を生成し、それを .whl ファイルへ変換します。既存の egg ファイルを " +#~ "bdist_wininst 配布物に変換することも可能です。" + +#~ msgid "" +#~ "Wheel is versioned. Every wheel file contains the version of the wheel " +#~ "specification and the implementation that packaged it. Hopefully the next " +#~ "migration can simply be to Wheel 2.0." +#~ msgstr "" +#~ "Wheel はバージョン付けされています。各 wheel ファイルは wheel 仕様および" +#~ "パッケージングに使われた実装のバージョンを含んでいます。次のマイグレーショ" +#~ "ンが単純に Wheel 2.0 へのものになれば良いのですが。" + +#~ msgid "Wheel is a reference to the other Python." +#~ msgstr "Wheel は、他の Python に対して参照するべきものとなっています。" + +#~ msgid "Changes" +#~ msgstr "変更点" + +#~ msgid "Since :pep:`427`, this specification has changed as follows:" +#~ msgstr ":pep:`427` 以来、この仕様には次のような修正が加えられました:" + +#~ msgid "" +#~ "PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" +#~ msgstr "" +#~ "PEP 受諾 (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" + +#~ msgid "This document has been placed into the public domain." +#~ msgstr "この文書はパブリックドメインに位置付けられる。" + +#~ msgid "``python -m twine check``" +#~ msgstr "``python -m twine check``" + +#~ msgid "``python -m twine register``" +#~ msgstr "``python -m twine register``" + +#~ msgid "``python -m twine upload``" +#~ msgstr "``python -m twine upload``" + +#~ msgid "``python -m setuptools-scm``" +#~ msgstr "``python -m setuptools-scm``" + +#~ msgid "" +#~ "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); " +#~ "see :doc:`Declaring project metadata ` for more detail" +#~ msgstr "" +#~ "プロジェクトの :doc:`コアとなるメタデータ ` (名前・バージョン・作者・その他) を含む ``[project]`` テーブル; 詳しく" +#~ "は、 :doc:`プロジェクトのメタデータを宣言する ` を見てください" + +#~ msgid "a ``[tool]`` table containing tool-specific configuration options" +#~ msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル" + +#~ msgid "" +#~ "A `content type `_ can be specified with the " +#~ "``long_description_content_type`` argument, which can be one of ``text/" +#~ "plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " +#~ "formatting, `reStructuredText (reST) `_, and the GitHub-" +#~ "flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "``long_description_content_type`` 引数に特に整形しない ``text/plain`` 、" +#~ "`reStructuredText (reST) `_ として解釈される ``text/x-" +#~ "rst`` 、`Markdown `_ の中で" +#~ "もGitHub方言のものとして解釈される ``text/markdown`` のうちのいずれかを与" +#~ "えることで、`コンテンツタイプ `_ を指定" +#~ "することができます。" + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "pipx については、 https://pypa.github.io/pipx/ でもっと学べます。" + +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr ":ref:`ビルド依存関係を宣言する `" + +#~ msgid "" +#~ "Read :ref:`declaring-project-metadata` for the full specification of the " +#~ "content allowed in the ``[project]`` table." +#~ msgstr "" +#~ "``[project]`` テーブルで許される内容の完全な仕様については、 :ref:`プロ" +#~ "ジェクトのメタデータを宣言する ` を読んでくだ" +#~ "さい。" + +#~ msgid ":ref:`declaring-project-metadata`" +#~ msgstr "" +#~ ":ref:`プロジェクトのメタデータを宣言する `" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `GitHub `__" +#~ msgstr "" +#~ ":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__" + +#~ msgid "" +#~ "trove-classifiers is the canonical source for `classifiers on PyPI " +#~ "`_, which project maintainers use to " +#~ "`systematically describe their projects `_ so that users " +#~ "can better find projects that match their needs on the PyPI." +#~ msgstr "" +#~ "trove-classifiers は、`PyPI における分類子 `_ の正統な源泉で、ユーザがそのニーズに即したプロジェクトを PyPI でよりう" +#~ "まく探し出せるように、プロジェクトの管理者が `プロジェクトを体系的に表現す" +#~ "る `_ のに使います。" + +#~ msgid "Declaring build system dependencies" +#~ msgstr "ビルドシステムの依存関係を宣言する" + +#, fuzzy +#~ msgid "" +#~ "The ``pyproject.toml`` file is written in `TOML `_. " +#~ "Among other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " +#~ "installed in order to run the project's build system successfully." +#~ msgstr "" +#~ "`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファ" +#~ "イル形式で、あるプロジェクトのビルドシステムが正常に動作するためにインス" +#~ "トールされていなければならない Python レベルの依存関係をすべて宣言するとい" +#~ "う目的のためにそのプロジェクトが提供するものです。" + +#~ msgid "Declaring project metadata" +#~ msgstr "プロジェクトのメタデータを宣言する" + +#~ msgid "" +#~ ":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " +#~ "consume. It defines the following specification as the canonical source " +#~ "for the format used." +#~ msgstr "" +#~ ":pep:`621` では、パッケージング関連のツールが使用するために、あるプロジェ" +#~ "クトの :ref:`コアとなるメタデータ ` を ``pyproject.toml`` " +#~ "ファイルにどのように書けば良いかを指定しています。使われるファイルフォー" +#~ "マットの基準となる仕様として、以下のようなものを定義しています。" + +#, fuzzy +#~ msgid "" +#~ "The keys defined in this specification MUST be in a table named " +#~ "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " +#~ "which are not defined by this specification. For tools wishing to store " +#~ "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " +#~ "table as defined in the :ref:`build dependency declaration specification " +#~ "`. The lack of a ``[project]`` table " +#~ "implicitly means the :term:`build backend ` will " +#~ "dynamically provide all keys." +#~ msgstr "" +#~ "この仕様で定義されるキーは、 ``pyproject.toml`` ファイルの中の " +#~ "``[project]`` という名前のテーブルに収容されていなければなりません。いかな" +#~ "るツールもこのテーブルにこの仕様で定義されていないキーを追加してはなりませ" +#~ "ん。自身の設定を ``pyproject.toml`` ファイルに記録しておきたいと願うツール" +#~ "は、 :ref:`ビルド時の依存関係を宣言するための仕様 ` で定義されている通りに ``[tool]`` テーブルを使うことができ" +#~ "ます。 ``[project]`` テーブルが欠落している場合は、ビルド用のバックエンド" +#~ "がすべてのキーを動的に提供するであろうということを暗黙理に意味しています。" + +#~ msgid "" +#~ "A ``.tar.gz`` source distribution (sdist) contains a single top-level " +#~ "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " +#~ "source files of the package. The name and version MUST match the metadata " +#~ "stored in the file. This directory must also contain a :file:`pyproject." +#~ "toml` in the format defined in :ref:`declaring-build-dependencies`, and a " +#~ "``PKG-INFO`` file containing metadata in the format described in the :ref:" +#~ "`core-metadata` specification. The metadata MUST conform to at least " +#~ "version 2.2 of the metadata specification." +#~ msgstr "" +#~ "``.tar.gz`` ソースコード配布物 (sdist) には、 ``{name}-{version}`` (例え" +#~ "ば ``foo-1.0``) と言う名前の単一のトップレベルディレクトリがあって、そこに" +#~ "パッケージのソールファイル群を含んでいます。 name と version は、ファイル" +#~ "内のメタデータと合致していなければなりません。このディレクトリは、 :ref:" +#~ "`declaring-build-dependencies` の中で定義されたフォーマットで書かれた :" +#~ "file:`pyproject.toml` ファイルや、 :ref:`core-metadata` 仕様内に記述された" +#~ "フォーマットで書かれたメタデータを含んだ ``PKG-INFO`` ファイルも含んでいな" +#~ "ければなりません。メタデータは、少なくともバージョン 2.2 のメタデータ仕様" +#~ "を満足するものでなければなりません。" + +#~ msgid "" +#~ "Read :pep:`517` and :pep:`518` for background and details on build tool " +#~ "configuration." +#~ msgstr "" +#~ "ビルドツールの設定に関する背景情報や詳細情報については、 :pep:`517` や :" +#~ "pep:`518` を読みましょう。" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr ":doc:`/guides/packaging-binary-extensions` について読みましょう。" + #~ msgid "And of course *setuptools* itself is not deprecated either." #~ msgstr "" #~ "そして、 *setuptools* それ自身もまた、非推奨ではないのはもちろんのことで" @@ -25148,9 +25237,6 @@ msgstr "" #~ "external-package-manager` で仕様化されていました。" #, fuzzy -#~| msgid "" -#~| "The Python installers for Windows include pip. You can make sure that " -#~| "pip is up-to-date by running:" #~ msgid "You can make sure that pip is up-to-date by running:" #~ msgstr "" #~ "Windows 用の Python インストーラは pip を含んでいます。次のようにすると " diff --git a/locales/ko/LC_MESSAGES/messages.po b/locales/ko/LC_MESSAGES/messages.po index a9f889379..12ada7a26 100644 --- a/locales/ko/LC_MESSAGES/messages.po +++ b/locales/ko/LC_MESSAGES/messages.po @@ -3,13 +3,14 @@ # This file is distributed under the same license as the Python Packaging User Guide package. # Tanat , 2022, 2023. # Dongseop , 2023. +# 고종환 , 2023. msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" -"PO-Revision-Date: 2023-05-09 13:33+0000\n" -"Last-Translator: Dongseop \n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" +"PO-Revision-Date: 2023-12-08 13:49+0000\n" +"Last-Translator: 고종환 \n" "Language-Team: Korean \n" "Language: ko\n" @@ -17,7 +18,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Weblate 4.18-dev\n" +"X-Generator: Weblate 5.3-dev\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -74,19 +75,15 @@ msgid "Documentation types" msgstr "문서 유형" #: ../source/contribute.rst:34 -#, fuzzy -#| msgid "" -#| "This project consists of four distinct documentation types with specific " -#| "purposes. When proposing new additions to the project please pick the " -#| "appropriate documentation type." msgid "" "This project consists of four distinct documentation types with specific " "purposes. The project aspires to follow the `Diátaxis process`_ for creating " "quality documentation. When proposing new additions to the project please " "pick the appropriate documentation type." msgstr "" -"이 프로젝트는 특정 목적을 가진 4가지 문서 유형으로 구성되어 있습니다. 프로젝" -"트에 대해 새로운 추가를 제안할 때 적절한 문서 유형을 선택하십시오." +"이 프로젝트는 특정 목적을 가진 4가지 문서 유형으로 구성되어 있습니다. 본 프로" +"젝트는 훌륭한 문서작성을 위해서`Diátaxis process`를 따르는 것을 열망합니다. " +"프로젝트에 대해 새로운 추가를 제안할 때 적절한 문서 유형을 선택하십시오." #: ../source/contribute.rst:42 ../source/index.rst:55 #: ../source/tutorials/index.rst:2 @@ -532,6 +529,7 @@ msgid "Deploying Python applications" msgstr "" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -550,6 +548,7 @@ msgid "Incomplete" msgstr "미완료" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -653,7 +652,7 @@ msgid "Unix (including Linux and macOS)" msgstr "" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "" @@ -672,6 +671,142 @@ msgstr "" msgid "Configuration management" msgstr "" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +msgid "What's an import package?" +msgstr "패키지 가져오기" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -945,7 +1080,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1084,145 +1219,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1230,46 +1372,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1277,26 +1419,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1613,24 +1755,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1639,22 +1785,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1662,7 +1808,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1671,43 +1817,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1798,14 +1944,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1813,11 +1960,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1826,11 +1973,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1839,70 +1986,71 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 #, fuzzy msgid "Import Package" msgstr "패키지 가져오기" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "모듈" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 #, fuzzy msgid "Package Index" msgstr "패키지 인덱스" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 #, fuzzy msgid "Per Project Index" msgstr "프로젝트별 인덱스" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1911,7 +2059,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1919,7 +2067,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1927,21 +2075,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1951,48 +2099,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2000,11 +2148,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2013,18 +2161,16 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 #, fuzzy msgid "Requirement Specifier" msgstr "요구 사항 지정자" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2040,12 +2186,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2204,7 +2350,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2273,14 +2419,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2636,8 +2782,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2812,6 +2957,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2820,14 +2973,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2835,36 +2988,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2885,14 +3038,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2932,11 +3085,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2944,7 +3097,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2952,16 +3105,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2971,256 +3124,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3230,78 +3195,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3310,24 +3236,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3336,7 +3262,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3348,13 +3274,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3362,12 +3288,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3375,69 +3301,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3445,42 +3330,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3488,58 +3373,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3547,44 +3432,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3594,17 +3479,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3613,13 +3498,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3629,7 +3514,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3637,21 +3522,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3660,22 +3545,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3683,23 +3568,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3708,11 +3593,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3720,95 +3605,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3816,7 +3701,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3824,7 +3709,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3833,7 +3718,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3843,78 +3728,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3922,7 +3807,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3930,14 +3815,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4051,96 +3928,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4155,9 +4023,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4439,7 +4307,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4544,6 +4412,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4572,7 +4441,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4748,7 +4617,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4807,33 +4676,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4841,148 +4710,148 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Translations" msgid "Install extras" msgstr "번역" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4990,107 +4859,107 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy msgid "Using a requirements file" msgstr "요구 사항 지정자" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5539,13 +5408,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5615,7 +5483,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5654,11 +5522,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6275,11 +6143,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6288,19 +6156,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6311,17 +6179,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6329,17 +6197,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6347,7 +6215,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6355,7 +6223,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6364,27 +6232,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6392,11 +6260,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6404,13 +6272,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6418,11 +6286,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6431,21 +6299,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6453,17 +6321,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6475,19 +6343,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6496,13 +6364,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6798,44 +6666,52 @@ msgstr "번역" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6843,39 +6719,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6884,52 +6760,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7682,8 +7558,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7800,89 +7676,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7890,129 +7803,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8447,8 +8411,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8459,9 +8423,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8520,13 +8483,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8539,18 +8501,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8559,18 +8521,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8581,42 +8543,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8625,22 +8587,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8648,15 +8610,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8665,14 +8627,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8685,17 +8647,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8703,17 +8665,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8725,17 +8687,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8746,34 +8708,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8781,44 +8743,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8827,18 +8789,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8849,17 +8811,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8867,17 +8829,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8887,17 +8849,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8907,17 +8869,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8927,18 +8889,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8949,18 +8911,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8988,7 +8950,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9007,24 +8969,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9032,21 +8994,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9054,17 +9016,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10437,25 +10399,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10466,86 +10420,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10554,35 +10475,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10590,32 +10511,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10623,41 +10544,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10666,14 +10587,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10681,7 +10602,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10689,33 +10610,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10723,25 +10644,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10752,63 +10673,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10816,71 +10737,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10888,28 +10809,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10918,22 +10839,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10941,29 +10862,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10973,7 +10894,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10981,25 +10902,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11007,99 +10928,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11108,38 +10983,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11147,7 +11022,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11155,18 +11030,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11175,7 +11050,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11186,7 +11061,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11204,7 +11079,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11213,70 +11088,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11378,41 +11250,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11420,20 +11292,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11441,27 +11313,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11469,19 +11353,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11489,7 +11373,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11497,7 +11381,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11505,31 +11389,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11643,91 +11527,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11737,11 +11621,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11749,43 +11633,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11793,64 +11677,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11858,13 +11742,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11872,36 +11756,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11910,13 +11794,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11924,20 +11808,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11945,7 +11829,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11955,11 +11839,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11967,7 +11851,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11977,18 +11861,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11997,7 +11881,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12008,63 +11892,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12075,33 +11959,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12110,3354 +11994,3349 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "번역" + +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:219 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:8 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:17 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:36 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "번역" +#: ../source/specifications/direct-url-data-structure.rst:34 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:189 -msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 -msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:42 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:51 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" -msgstr "" - -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:98 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:145 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:158 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 -msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "패키지 가져오기" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 -msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 -msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:182 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:230 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 -msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "문서 유형" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/index.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -msgid "package" -msgstr "패키지 가져오기" - -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 -msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "문서 유형" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." -msgstr "" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "번역" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "문서 유형" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 -msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:69 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:110 +msgid "" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "문서 유형" - -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "번역" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15465,7 +15344,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15474,11 +15353,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15489,21 +15368,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15515,7 +15394,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15526,7 +15405,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15538,41 +15417,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15580,7 +15459,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15588,58 +15467,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15647,7 +15526,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15655,13 +15534,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15670,7 +15549,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15679,18 +15558,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15698,7 +15577,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15708,11 +15587,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15720,15 +15599,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15736,11 +15615,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15748,29 +15627,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15779,11 +15658,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15791,14 +15670,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15807,7 +15686,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15941,10 +15820,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16114,23 +15993,23 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy msgid "Definitions" msgstr "명세서" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16138,7 +16017,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16146,19 +16025,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16166,25 +16045,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "번역" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16192,26 +16071,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16219,7 +16098,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16227,63 +16106,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16291,11 +16170,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16304,7 +16183,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16314,7 +16193,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16323,7 +16202,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16331,23 +16210,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16361,7 +16240,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16369,7 +16248,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16381,36 +16260,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16418,21 +16297,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16440,35 +16323,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16476,48 +16359,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16525,7 +16408,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16533,11 +16416,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16545,11 +16428,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16557,20 +16440,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16579,13 +16462,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16595,29 +16478,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "번역" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16628,14 +16511,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16643,23 +16526,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "번역" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16668,11 +16551,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16682,11 +16565,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16696,11 +16579,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16708,11 +16591,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16723,11 +16606,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16735,11 +16618,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16747,11 +16630,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16761,11 +16644,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16773,11 +16656,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16785,11 +16668,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16797,11 +16680,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16810,11 +16693,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16823,11 +16706,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16837,7 +16720,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16845,69 +16728,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16915,48 +16798,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16967,7 +16850,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16977,17 +16860,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16996,18 +16879,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17018,7 +16901,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17026,30 +16909,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17057,30 +16940,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17088,60 +16971,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17150,79 +17033,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17231,7 +17114,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17239,31 +17122,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17271,7 +17154,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17280,7 +17163,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17290,14 +17173,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17306,29 +17189,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "번역" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17337,27 +17220,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17367,7 +17250,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17377,13 +17260,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17602,7 +17485,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17610,7 +17493,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17621,15 +17504,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17637,7 +17520,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17645,7 +17528,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17657,43 +17540,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17702,20 +17585,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19017,28 +18900,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Macedonian `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -896,7 +1033,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1033,145 +1170,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1179,46 +1323,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1226,26 +1370,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1562,24 +1706,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1588,22 +1736,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1611,7 +1759,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1620,43 +1768,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1747,14 +1895,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Jajce(Egg)" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1762,11 +1911,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1775,11 +1924,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1788,67 +1937,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1857,7 +2007,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1865,7 +2015,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1873,21 +2023,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1897,48 +2047,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1946,11 +2096,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1959,17 +2109,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1985,12 +2133,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2149,7 +2297,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2218,14 +2366,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2581,8 +2729,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2757,6 +2904,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2765,14 +2920,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2780,36 +2935,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2830,14 +2985,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2877,11 +3032,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2889,7 +3044,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2897,16 +3052,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2916,256 +3071,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3175,78 +3142,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3255,24 +3183,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3281,7 +3209,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3293,13 +3221,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3307,12 +3235,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3320,69 +3248,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3390,42 +3277,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3433,58 +3320,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3492,44 +3379,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3539,17 +3426,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3558,13 +3445,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3574,7 +3461,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3582,21 +3469,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3605,22 +3492,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3628,23 +3515,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3653,11 +3540,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3665,95 +3552,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3761,7 +3648,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3769,7 +3656,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3778,7 +3665,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3788,78 +3675,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3867,7 +3754,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3875,14 +3762,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3996,96 +3875,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4100,9 +3970,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4384,7 +4254,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4489,6 +4359,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4517,7 +4388,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4693,7 +4564,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4752,33 +4623,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4786,146 +4657,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4933,106 +4804,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5481,13 +5352,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5557,7 +5427,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5596,11 +5466,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6217,11 +6087,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6230,19 +6100,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6253,17 +6123,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6271,17 +6141,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6289,7 +6159,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6297,7 +6167,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6306,27 +6176,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6334,11 +6204,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6346,13 +6216,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6360,11 +6230,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6373,21 +6243,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6395,17 +6265,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6417,19 +6287,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6438,13 +6308,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6738,44 +6608,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6783,39 +6661,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6824,52 +6702,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7622,8 +7500,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7740,89 +7618,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7830,129 +7745,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8387,8 +8353,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8399,9 +8365,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8460,13 +8425,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8479,18 +8443,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8499,18 +8463,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8521,42 +8485,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8565,22 +8529,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8588,15 +8552,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8605,14 +8569,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8625,17 +8589,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8643,17 +8607,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8665,17 +8629,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8686,34 +8650,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8721,44 +8685,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8767,18 +8731,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8789,17 +8753,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8807,17 +8771,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8827,17 +8791,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8847,17 +8811,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8867,18 +8831,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8889,18 +8853,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8928,7 +8892,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8947,24 +8911,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8972,21 +8936,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8994,17 +8958,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10377,25 +10341,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10406,86 +10362,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10494,35 +10417,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10530,32 +10453,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10563,41 +10486,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10606,14 +10529,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10621,7 +10544,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10629,33 +10552,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10663,25 +10586,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10692,63 +10615,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10756,71 +10679,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10828,28 +10751,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10858,22 +10781,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10881,29 +10804,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10913,7 +10836,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10921,25 +10844,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10947,99 +10870,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11048,38 +10925,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11087,7 +10964,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11095,18 +10972,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11115,7 +10992,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11126,7 +11003,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11144,7 +11021,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11153,70 +11030,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11318,41 +11192,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11360,20 +11234,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11381,27 +11255,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11409,19 +11295,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11429,7 +11315,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11437,7 +11323,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11445,31 +11331,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11583,91 +11469,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11677,11 +11563,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11689,43 +11575,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11733,64 +11619,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11798,13 +11684,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11812,36 +11698,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11850,13 +11736,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11864,20 +11750,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11885,7 +11771,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11895,11 +11781,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11907,7 +11793,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11917,18 +11803,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11937,7 +11823,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11948,63 +11834,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12015,33 +11901,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12050,3347 +11936,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:69 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:79 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 -msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 -msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 -msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:110 +msgid "" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:119 +msgid "" +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 -msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:44 -msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:300 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:65 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:81 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 -msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:96 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pyproject-toml.rst:14 +msgid "" +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 -msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:346 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:359 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:32 -msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:398 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:411 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:427 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15398,7 +15279,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15407,11 +15288,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15422,21 +15303,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15448,7 +15329,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15459,7 +15340,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15471,41 +15352,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15513,7 +15394,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15521,58 +15402,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15580,7 +15461,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15588,13 +15469,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15603,7 +15484,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15612,18 +15493,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15631,7 +15512,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15641,11 +15522,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15653,15 +15534,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15669,11 +15550,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15681,29 +15562,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15712,11 +15593,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15724,14 +15605,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15740,7 +15621,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15874,10 +15755,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16047,22 +15928,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16070,7 +15951,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16078,19 +15959,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16098,24 +15979,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16123,26 +16004,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16150,7 +16031,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16158,63 +16039,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16222,11 +16103,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16235,7 +16116,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16245,7 +16126,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16254,7 +16135,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16262,23 +16143,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16292,7 +16173,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16300,7 +16181,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16312,36 +16193,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16349,21 +16230,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16371,35 +16256,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16407,48 +16292,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16456,7 +16341,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16464,11 +16349,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16476,11 +16361,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16488,20 +16373,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16510,13 +16395,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16526,28 +16411,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16558,14 +16443,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16573,22 +16458,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16597,11 +16482,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16611,11 +16496,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16625,11 +16510,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16637,11 +16522,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16652,11 +16537,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16664,11 +16549,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16676,11 +16561,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16690,11 +16575,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16702,11 +16587,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16714,11 +16599,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16726,11 +16611,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16739,11 +16624,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16752,11 +16637,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16766,7 +16651,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16774,69 +16659,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16844,48 +16729,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16896,7 +16781,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16906,17 +16791,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16925,18 +16810,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16947,7 +16832,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16955,30 +16840,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16986,30 +16871,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17017,60 +16902,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17079,79 +16964,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17160,7 +17045,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17168,31 +17053,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17200,7 +17085,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17209,7 +17094,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17219,14 +17104,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17235,28 +17120,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17265,27 +17150,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17295,7 +17180,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17305,13 +17190,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17530,7 +17415,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17538,7 +17423,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17549,15 +17434,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17565,7 +17450,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17573,7 +17458,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17585,43 +17470,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17630,20 +17515,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18945,28 +18830,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "Прочитајте за :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Portuguese (Brazil) \n" @@ -19,7 +19,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n > 1;\n" -"X-Generator: Weblate 5.0-dev\n" +"X-Generator: Weblate 5.3-rc\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -70,19 +70,14 @@ msgid "" "By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " "Conduct`__." msgstr "" -"Ao contribuir para o |PyPUG|, espera-se que você siga o `Código de Conduta " -"`__ da PSF." +"Ao contribuir para o |PyPUG|, espera-se que você siga o `Código de " +"Conduta`__ da PSF." #: ../source/contribute.rst:32 msgid "Documentation types" msgstr "Tipos de documentação" #: ../source/contribute.rst:34 -#, fuzzy -#| msgid "" -#| "This project consists of four distinct documentation types with specific " -#| "purposes. When proposing new additions to the project please pick the " -#| "appropriate documentation type." msgid "" "This project consists of four distinct documentation types with specific " "purposes. The project aspires to follow the `Diátaxis process`_ for creating " @@ -90,8 +85,9 @@ msgid "" "pick the appropriate documentation type." msgstr "" "Este projeto consiste em quatro tipos de documentação distintos com " -"finalidades específicas. Ao propor novas adições ao projeto, escolha o tipo " -"de documentação apropriado." +"finalidades específicas. O projeto aspira seguir a o `processo Diátaxis`_ " +"para criar documentação de qualidade. Ao propor novas adições ao projeto, " +"escolha o tipo de documentação apropriado." #: ../source/contribute.rst:42 ../source/index.rst:55 #: ../source/tutorials/index.rst:2 @@ -150,12 +146,6 @@ msgid "Specifications" msgstr "Especificações" #: ../source/contribute.rst:69 -#, fuzzy -#| msgid "" -#| "Specifications are reference documention focused on comprehensively " -#| "documenting an agreed-upon interface for interoperability between " -#| "packaging tools. :doc:`example specification-style document " -#| "`." msgid "" "Specifications are reference documentation focused on comprehensively " "documenting an agreed-upon interface for interoperability between packaging " @@ -180,16 +170,12 @@ msgstr "" "projeto `packaging.python.org`_ no Weblate para contribuir." #: ../source/contribute.rst:80 -#, fuzzy -#| msgid "" -#| "If you are experiencing issues while you are working on translations, " -#| "please open an issue on `Github`_." msgid "" "If you are experiencing issues while you are working on translations, please " "open an issue on `GitHub`_." msgstr "" "Se você está tendo problemas enquanto trabalha nas traduções, relate o " -"problema no `Github`_." +"problema no `GitHub`_." #: ../source/contribute.rst:85 msgid "" @@ -266,22 +252,16 @@ msgstr "" "``pip``:" #: ../source/contribute.rst:137 -#, fuzzy -#| msgid "" -#| "Python 3.8. Our build scripts are usually tested with Python 3.8 only. " -#| "See the :doc:`Hitchhiker's Guide to Python installation instructions " -#| "` to install Python 3.8 on your " -#| "operating system." msgid "" "Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " "the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " "system." msgstr "" -"Python 3.8. Nossos scripts de construção são geralmente testados com Python " -"3.8. Consulte o :doc:`Guia do mochileiro para as instruções de instalação do " -"Python ` para instalar o Python 3.8 em " -"seu sistema operacional." +"Python 3.11. Nossos scripts de construção são geralmente testados com Python " +"3.11. Consulte o :doc:`Guia do mochileiro para as instruções de instalação " +"do Python ` para instalar o Python 3.11 " +"em seu sistema operacional." #: ../source/contribute.rst:141 msgid "" @@ -624,6 +604,7 @@ msgid "Deploying Python applications" msgstr "Fazendo deploy de aplicações Python" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -642,6 +623,7 @@ msgid "Incomplete" msgstr "Incompleta" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -707,12 +689,6 @@ msgstr "" "instalação Python no computador." #: ../source/discussions/deploying-python-applications.rst:71 -#, fuzzy -#| msgid "" -#| "A big advantage of Pynsist is that the Windows packages can be built on " -#| "Linux. There are several examples for different kinds of programs " -#| "(console, GUI) in the `documentation `. The tool is " -#| "released under the MIT-licence." msgid "" "A big advantage of Pynsist is that the Windows packages can be built on " "Linux. There are several examples for different kinds of programs (console, " @@ -721,8 +697,8 @@ msgid "" msgstr "" "Uma grande vantagem do Pynsist é que os pacotes do Windows podem ser " "construídos no Linux. Existem vários exemplos para diferentes tipos de " -"programas (console, GUI) na `documentação `. A ferramenta é " -"lançada sob a licença do MIT." +"programas (console, GUI) na :any:`documentação `. A " +"ferramenta é lançada sob a licença do MIT." #: ../source/discussions/deploying-python-applications.rst:77 msgid "Application bundles" @@ -779,7 +755,7 @@ msgid "Unix (including Linux and macOS)" msgstr "Unix (incluindo Linux e macOS)" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "pex" @@ -805,6 +781,147 @@ msgstr "" msgid "Configuration management" msgstr "Gerenciamento de configuração" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution package vs. import package" +msgstr "Pacote de Distribuição" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +#, fuzzy +#| msgid "Linux distribution packages" +msgid "What's a distribution package?" +msgstr "Pacotes de distribuição Linux" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "e importe o pacote:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -1131,94 +1248,101 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:6 msgid "Is ``setup.py`` deprecated?" -msgstr "" +msgstr "``setup.py`` foi descontinuado?" #: ../source/discussions/setup-py-deprecated.rst:8 msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." -msgstr "" +msgstr "Não, :term:`setup.py` e :ref:`setuptools` não foram descontinuados." #: ../source/discussions/setup-py-deprecated.rst:10 +#, fuzzy +#| msgid "" +#| "Setuptools is perfectly usable as a :term:`build backend` for packaging " +#| "Python projects. And :file:`setup.py` is a valid configuration file for :" +#| "ref:`setuptools` that happens to be written in Python, instead of in " +#| "*TOML* for example (a similar practice is used by other tools like *nox* " +#| "and its :file:`nox.py` configuration file, or *pytest* and :file:" +#| "`conftest.py`)." msgid "" "Setuptools is perfectly usable as a :term:`build backend` for packaging " "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" +"Setuptools é perfeitamente utilizável como um :term:`backend de construção` " +"para empacotar projetos Python. E :file:`setup.py` é um arquivo de " +"configuração válido para :ref:`setuptools` que é escrito em Python, em vez " +"de em *TOML* por exemplo (uma prática semelhante é usada por outras " +"ferramentas como *nox* e seu arquivo de configuração :file:`nox.py`, ou " +"*pytest* e :file:`conftest.py`)." #: ../source/discussions/setup-py-deprecated.rst:18 msgid "" "However, ``python setup.py`` and the use of :file:`setup.py` as a command " "line tool are deprecated." msgstr "" +"No entanto, ``python setup.py`` e o uso de :file:`setup.py` como uma " +"ferramenta de linha de comando foram descontinuados." #: ../source/discussions/setup-py-deprecated.rst:21 msgid "" "This means that commands such as the following **MUST NOT** be run anymore:" msgstr "" +"Isso significa que comandos como os seguintes **NÃO DEVEM** ser mais " +"executados:" #: ../source/discussions/setup-py-deprecated.rst:23 #: ../source/discussions/setup-py-deprecated.rst:35 #: ../source/guides/modernize-setup-py-project.rst:32 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python setup.py install``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python setup.py install``" #: ../source/discussions/setup-py-deprecated.rst:24 #: ../source/discussions/setup-py-deprecated.rst:37 #: ../source/guides/modernize-setup-py-project.rst:34 msgid "``python setup.py develop``" -msgstr "" +msgstr "``python setup.py develop``" #: ../source/discussions/setup-py-deprecated.rst:25 #: ../source/discussions/setup-py-deprecated.rst:39 #: ../source/guides/modernize-setup-py-project.rst:36 -#, fuzzy msgid "``python setup.py sdist``" -msgstr "python_requires" +msgstr "``python setup.py sdist``" #: ../source/discussions/setup-py-deprecated.rst:26 #: ../source/discussions/setup-py-deprecated.rst:41 #: ../source/guides/modernize-setup-py-project.rst:38 msgid "``python setup.py bdist_wheel``" -msgstr "" +msgstr "``python setup.py bdist_wheel``" #: ../source/discussions/setup-py-deprecated.rst:30 msgid "What commands should be used instead?" -msgstr "" +msgstr "Quais comandos devem ser usados?" #: ../source/discussions/setup-py-deprecated.rst:33 #: ../source/guides/modernize-setup-py-project.rst:30 -#, fuzzy -#| msgid "Rarely Used Fields" msgid "Deprecated" -msgstr "Campos raramente usados" +msgstr "Descontinuado" #: ../source/discussions/setup-py-deprecated.rst:33 #: ../source/guides/modernize-setup-py-project.rst:30 -#, fuzzy -#| msgid "Tool recommendations" msgid "Recommendation" -msgstr "Recomendações de ferramentas" +msgstr "Recomendação" #: ../source/discussions/setup-py-deprecated.rst:35 #: ../source/guides/modernize-setup-py-project.rst:32 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m pip install .``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python -m pip install .``" #: ../source/discussions/setup-py-deprecated.rst:37 #: ../source/guides/modernize-setup-py-project.rst:34 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m pip install --editable .``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python -m pip install --editable .``" #: ../source/discussions/setup-py-deprecated.rst:39 msgid "``python -m build`` [#needs-build]_" -msgstr "" +msgstr "``python -m build`` [#needs-build]_" #: ../source/discussions/setup-py-deprecated.rst:45 msgid "" @@ -1227,6 +1351,10 @@ msgid "" "what ``python -m build`` does. If necessary the ``--sdist`` and ``--wheel`` " "options can be used to generate only one or the other." msgstr "" +"Isto requer a dependência de :ref:`build`. É recomendado sempre construir e " +"publicar tanto a distribuição fonte quanto a wheel de um projeto, que é o " +"que ``python -m build`` faz. Se necessário as opções ``--sdist`` e ``--" +"wheel`` podem ser usadas para gerar apenas uma ou outra." #: ../source/discussions/setup-py-deprecated.rst:52 msgid "" @@ -1239,6 +1367,15 @@ msgid "" "on the local filesystem as argument to its ``install`` sub-command. So this " "would also be a valid command: ``python -m pip install path/to/project``." msgstr "" +"Para instalar um projeto baseado no setuptools, era comum executar o comando " +"``install`` do arquivo :file:`setup.py`, como, por exemplo, ``python setup." +"py install``. Atualmente, o método recomendado é utilizar o :ref:`pip` " +"diretamente com um comando como este: ``python -m pip install .``. O ponto " +"``.`` representa o caminho do sistema de arquivos, sendo a notação para o " +"diretório atual. De fato, o *pip* aceita um caminho para o diretório da " +"árvore de fontes do projeto no sistema de arquivos local como argumento para " +"o seu subcomando ``install``. Portanto, este também seria um comando válido: " +"``python -m pip install caminho/para/projeto``." #: ../source/discussions/setup-py-deprecated.rst:65 msgid "" @@ -1246,6 +1383,10 @@ msgid "" "``python setup.py develop`` one can use the ``--editable`` option of pip's " "*install* sub-command: ``python -m pip install --editable .``." msgstr "" +"Quanto à instalação no modo *develop*, também conhecido como modo " +"*editable*, em vez de ``python setup.py develop``, é possível utilizar a " +"opção ``--editable`` do subcomando *install* do *pip* da seguinte forma: " +"``python -m pip install --editable .``." #: ../source/discussions/setup-py-deprecated.rst:70 msgid "" @@ -1257,286 +1398,302 @@ msgid "" "generate only one or the other. Note that the build tool needs to be " "installed separately." msgstr "" +"Um método recomendado, simples e direto para construir :term:`distribuições " +"fonte ` e :term:`wheels ` é usar " +"a ferramenta :ref:`build` com um comando como ``python -m build``, que " +"aciona a geração de ambos os formatos de distribuição. Se necessário, as " +"opções ``--sdist`` e ``--wheel`` podem ser usadas para gerar apenas um ou " +"outro. Observe que a ferramenta de construção precisa ser instalada " +"separadamente." #: ../source/discussions/setup-py-deprecated.rst:80 msgid "" "The command ``python setup.py install`` was deprecated in setuptools version " "*58.3.0*." msgstr "" +"O comando ``python setup.py install`` foi descontinuado na versão *58.3.0* " +"do setuptools." #: ../source/discussions/setup-py-deprecated.rst:85 msgid "What about other commands?" -msgstr "" +msgstr "E quanto a outros comandos?" #: ../source/discussions/setup-py-deprecated.rst:87 msgid "What are some replacements for the other ``python setup.py`` commands?" msgstr "" +"Quais são algumas substituições para os outros comandos ``python setup.py``?" #: ../source/discussions/setup-py-deprecated.rst:91 -#, fuzzy msgid "``python setup.py test``" -msgstr "python_requires" +msgstr "``python setup.py test``" #: ../source/discussions/setup-py-deprecated.rst:93 msgid "The recommendation is to use a test runner such as pytest_." -msgstr "" +msgstr "A recomendação é usar um executor de testes como pytest_." #: ../source/discussions/setup-py-deprecated.rst:99 msgid "" "``python setup.py check``, ``python setup.py register``, and ``python setup." "py upload``" msgstr "" +"``python setup.py check``, ``python setup.py register`` e ``python setup.py " +"upload``" #: ../source/discussions/setup-py-deprecated.rst:101 msgid "A trusted replacement is :ref:`twine`:" -msgstr "" +msgstr "Um substituto confiável é :ref:`twine`:" #: ../source/discussions/setup-py-deprecated.rst:103 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine check``" -msgstr "Sim (``python -m pip uninstall``)" +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" #: ../source/discussions/setup-py-deprecated.rst:104 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine register``" -msgstr "Sim (``python -m pip uninstall``)" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "``python -m twine register dist/*.whl`` [#not-pypi]_" #: ../source/discussions/setup-py-deprecated.rst:105 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine upload``" -msgstr "Sim (``python -m pip uninstall``)" +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" -#: ../source/discussions/setup-py-deprecated.rst:109 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"Não é necessário, nem suportado em :term:`PyPI `. Mas pode ser necessário em outros :term:`índices de pacotes " +"` (por exemplo, :ref:`devpi`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" -msgstr "python_requires" +msgstr "``python setup.py --version``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" +"Uma possível solução de substituição (entre outras) é contar com setuptools-" +"scm_:" -#: ../source/discussions/setup-py-deprecated.rst:113 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m setuptools-scm``" -msgstr "Sim (``python -m pip uninstall``)" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" -msgstr "" +msgstr "Comandos restantes" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" +"Este guia não faz sugestões de soluções de substituição para esses comandos:" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" -msgstr "" +msgstr "``alias``" -#: ../source/discussions/setup-py-deprecated.rst:127 -#, fuzzy -#| msgid "``test``" +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" -msgstr "``test``" +msgstr "``bdist``" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" -msgstr "" +msgstr "``bdist_dumb``" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" -msgstr "" +msgstr "``bdist_egg``" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" -msgstr "" +msgstr "``bdist_rpm``" -#: ../source/discussions/setup-py-deprecated.rst:131 -#, fuzzy -#| msgid "build" +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" -msgstr "construir" +msgstr "``build``" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" -msgstr "" +msgstr "``build_clib``" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" -msgstr "" +msgstr "``build_ext``" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" -msgstr "" +msgstr "``build_py``" -#: ../source/discussions/setup-py-deprecated.rst:135 -#, fuzzy -#| msgid "``gui-scripts``" +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" -msgstr "``gui-scripts``" +msgstr "``build_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" -msgstr "" +msgstr "``clean``" -#: ../source/discussions/setup-py-deprecated.rst:137 -#, fuzzy -#| msgid "``pypinfo``" +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" -msgstr "``pypinfo``" +msgstr "``dist_info``" -#: ../source/discussions/setup-py-deprecated.rst:138 -#, fuzzy -#| msgid "**easy_install**" +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" -msgstr "**easy_install**" +msgstr "``easy_install``" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" -msgstr "" +msgstr "``editable_wheel``" -#: ../source/discussions/setup-py-deprecated.rst:140 -#, fuzzy -#| msgid "``pypinfo``" +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" -msgstr "``pypinfo``" +msgstr "``egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:141 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" -msgstr "pip install app" +msgstr "``install``" -#: ../source/discussions/setup-py-deprecated.rst:142 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" -msgstr "pip install app" +msgstr "``install_data``" -#: ../source/discussions/setup-py-deprecated.rst:143 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" -msgstr "install_requires" +msgstr "``install_egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:144 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" -msgstr "install_requires" +msgstr "``install_headers``" -#: ../source/discussions/setup-py-deprecated.rst:145 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" -msgstr "install_requires" +msgstr "``install_lib``" -#: ../source/discussions/setup-py-deprecated.rst:146 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" -msgstr "console_scripts" +msgstr "``install_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" -msgstr "" +msgstr "``rotate``" -#: ../source/discussions/setup-py-deprecated.rst:148 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" -msgstr "scripts" +msgstr "``saveopts``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" -msgstr "" +msgstr "``setopt``" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" -msgstr "" +msgstr "``upload_docs``" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" -msgstr "" +msgstr "E quanto aos comandos personalizados?" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " "any other similar tool. Some examples of such tools are: chuy, make, nox or " "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" +"Da mesma forma, os comandos personalizados no :file:`setup.py` foram " +"descontinuados. A recomendação é migrar esses comandos personalizados para " +"uma ferramenta executora de tarefas ou qualquer outra ferramenta semelhante. " +"Alguns exemplos de tais ferramentas são: chuy, make, nox ou tox, pydoit, " +"pyinvoke, taskipy e thx." -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" -msgstr "" +msgstr "E quanto às etapas personalizadas de construção?" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" +"Etapas personalizadas de construção que, por exemplo, sobrescrevem etapas " +"existentes como ``build_py``, ``build_ext`` e ``bdist_wheel`` ou adicionam " +"novas etapas de compilação não foram descontinuadas. Eles serão chamados " +"automaticamente conforme o esperado." -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" -msgstr "" +msgstr "Deve o ``setup.py`` ser excluído?" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" +"Embora o uso de :file:`setup.py` como um script executável tenha sido " +"descontinuado, seu uso como um arquivo de configuração para setuptools é " +"absolutamente aceitável. Provavelmente não há necessidade de modificação em :" +"file:`setup.py`." -#: ../source/discussions/setup-py-deprecated.rst:181 -#, fuzzy -#| msgid "pyproject.toml" +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" -msgstr "pyproject.toml" +msgstr "``pyproject.toml`` é obrigatório?" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" +"Embora ainda não seja tecnicamente necessário, é **FORTEMENTE RECOMENDADO** " +"que um projeto tenha um arquivo :file:`pyproject.toml` na raiz de sua árvore " +"de fontes com um conteúdo como este:" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." -msgstr "" +msgstr "O guia :ref:`modernize-setup-py-project` tem mais detalhes sobre isso." -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " "table is to assume that the :term:`build backend ` is " "setuptools." msgstr "" +"O comportamento de fallback padrão para um :term:`frontend de construção " +"` na ausência de um arquivo :file:`pyproject.toml` e sua " +"tabela ``[build-system]`` é assumir que o :term:`backend de construção " +"` é o setuptools." -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" -msgstr "" +msgstr "Por que? O que isso tudo quer dizer?" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" +"Uma maneira de ver isso é que o escopo do setuptools agora foi reduzido à " +"função de um backend de construção." -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" -msgstr "" +msgstr "Onde posso ler mais sobre isso?" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" -msgstr "" +msgstr "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" -msgstr "" +msgstr ":doc:`setuptools:deprecated/commands`" #: ../source/discussions/src-layout-vs-flat-layout.rst:5 msgid "src layout vs flat layout" @@ -1958,13 +2115,6 @@ msgid "For example, here is a table for using :ref:`hatch`:" msgstr "Por exemplo, aqui está uma tabela para usar :ref:`hatch`:" #: ../source/flow.rst:85 -#, fuzzy -#| msgid "" -#| "With such a table in the :file:`pyproject.toml` file, a \"frontend\" tool " -#| "like :ref:`build` can run your chosen build tool's \"backend\" to create " -#| "the build artifacts. Your build tool may also provide its own frontend. " -#| "An install tool like :ref:`pip` also acts as a frontend when it runs your " -#| "build tool's backend to install from a source distribution." msgid "" "With such a table in the :file:`pyproject.toml` file, a \":term:`frontend " "`\" tool like :ref:`build` can run your chosen build tool's " @@ -1973,13 +2123,13 @@ msgid "" "`pip` also acts as a frontend when it runs your build tool's backend to " "install from a source distribution." msgstr "" -"Com tal tabela no arquivo :file:`pyproject.toml`, uma ferramenta " -"\"frontend\" como :ref:`build` pode executar o \"backend\" da ferramenta de " -"compilação escolhida para criar os artefatos de compilação. Sua ferramenta " -"de compilação também pode fornecer seu próprio frontend. Uma ferramenta de " -"instalação como :ref:`pip` também atua como frontend quando executa o " -"backend da sua ferramenta de construção para instalar a partir de uma " -"distribuição fonte." +"Com tal tabela no arquivo :file:`pyproject.toml`, uma ferramenta \":term:" +"`frontend `\" como :ref:`build` pode executar o \":term:" +"`backend `\" da ferramenta de compilação escolhida para criar " +"os artefatos de compilação. Sua ferramenta de compilação também pode " +"fornecer seu próprio frontend. Uma ferramenta de instalação como :ref:`pip` " +"também atua como frontend quando executa o backend da sua ferramenta de " +"construção para instalar a partir de uma distribuição fonte." #: ../source/flow.rst:94 msgid "" @@ -1993,30 +2143,34 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," msgstr "" "uma tabela ``[project]`` contendo os :doc:`Metadados Principais ` (nome, versão, autor e assim por diante) do " -"projeto; veja :doc:`Declarando os metadados do projeto ` para mais detalhes" +"specifications/core-metadata/>` (nome, versão, autor e assim por diante)," -#: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" "uma tabela ``[tool]`` contendo opções de configuração específicas da " -"ferramenta" +"ferramenta." + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" +"Consulte o :ref:`guia pyproject.toml ` para um guia " +"completo para a configuração de ``pyproject.toml``." -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "Artefatos de construção" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "A distribuição fonte (sdist)" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -2031,7 +2185,7 @@ msgstr "" "usuários finais onde alguma etapa de compilação local é necessária (como uma " "extensão C)." -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" @@ -2039,18 +2193,18 @@ msgstr "" "O pacote :ref:`build` sabe como invocar sua ferramenta de construção para " "criar uma destas:" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" "Ou sua ferramenta de construção pode fornecer sua própria interface para " "criar um sdist." -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "As distribuições de construídas (wheels)" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -2063,7 +2217,7 @@ msgstr "" "descompactado no diretório ``site-packages``. Isso torna a instalação mais " "rápida e conveniente para os usuários finais." -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -2078,13 +2232,13 @@ msgstr "" "disponível, ferramentas como :ref:`pip` voltarão a instalar a distribuição " "fonte." -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" "Ou sua ferramenta de construção pode fornecer sua própria interface para " "criar um wheel." -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " @@ -2094,11 +2248,11 @@ msgstr "" "wheel da fonte no diretório atual; os exemplos acima são deliberadamente " "específicos." -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "Enviando os arquivos de distribuição" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" @@ -2106,17 +2260,17 @@ msgstr "" "A ferramenta :ref:`twine` pode enviar artefatos de construção para PyPI para " "distribuição, usando um comando como:" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" "Ou sua ferramenta de construção pode fornecer sua própria interface para " "envio." -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "Baixando e instalando" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" @@ -2126,7 +2280,7 @@ msgstr "" "o pacote em seu ambiente Python. Normalmente isso é feito com :ref:`pip`, " "usando um comando como:" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -2152,7 +2306,7 @@ msgstr "" #: ../source/glossary.rst:14 msgid "Build Backend" -msgstr "" +msgstr "Backend de construção" #: ../source/glossary.rst:17 msgid "" @@ -2161,6 +2315,11 @@ msgid "" "`wheel ` from it. The build is delegated to the backend by a :term:" "`frontend `. All backends offer a standardized interface." msgstr "" +"Uma biblioteca que pega uma árvore de fontes ou :term:`distribuição fonte " +"` e constrói uma distribuição de código-" +"fonte ou :term:`wheel ` a partir dela. A construção é delegada ao " +"backend por um :term:`frontend `. Todos os backends oferecem " +"uma interface padronizada." #: ../source/glossary.rst:24 msgid "" @@ -2168,10 +2327,13 @@ msgid "" "hatchling `, :ref:`maturin`, :ref:`meson-python`, :ref:`scikit-build-" "core`, and :ref:`setuptools`." msgstr "" +"Exemplos de backends de construção são :ref:`flit-core do flit `, :ref:" +"`hatchling do hatch `, :ref:`maturin`, :ref:`meson-python`, :ref:" +"`scikit-build-core` e :ref:`setuptools`." #: ../source/glossary.rst:32 msgid "Build Frontend" -msgstr "" +msgstr "Frontend de construção" #: ../source/glossary.rst:35 msgid "" @@ -2181,10 +2343,15 @@ msgid "" "building is delegated to each source tree's :term:`build backend `." msgstr "" +"Uma ferramenta que os usuários podem executar que pega árvores de fontes " +"arbitrárias ou :term:`distribuições fonte ` e constrói distribuições fontes ou :term:`wheels ` a " +"partir delas. A construção real é delegada ao :term:`backend de construção " +"` de cada árvore de fontes." #: ../source/glossary.rst:42 msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." -msgstr "" +msgstr "Exemplos de frontends de construção são :ref:`pip` e :ref:`build`." #: ../source/glossary.rst:44 msgid "Built Distribution" @@ -2226,6 +2393,15 @@ msgstr "" "final irá baixar da Internet e instalar." #: ../source/glossary.rst:64 +#, fuzzy +#| msgid "" +#| "A distribution package is more commonly referred to with the single words " +#| "\"package\" or \"distribution\", but this guide may use the expanded term " +#| "when more clarity is needed to prevent confusion with an :term:`Import " +#| "Package` (which is also commonly called a \"package\") or another kind of " +#| "distribution (e.g. a Linux distribution or the Python language " +#| "distribution), which are often referred to with the single term " +#| "\"distribution\"." msgid "" "A distribution package is more commonly referred to with the single words " "\"package\" or \"distribution\", but this guide may use the expanded term " @@ -2233,7 +2409,8 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" "Um pacote de distribuição é mais comumente referido com as palavras " "\"pacote\" ou \"distribuição\", mas este guia pode usar o termo expandido " @@ -2243,11 +2420,11 @@ msgstr "" "linguagem Python), que são frequentemente referidos com o único termo " "\"distribuição\"." -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Egg" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -2260,11 +2437,11 @@ msgstr "" "deprecated/python_eggs>` e `Python Eggs `_" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "Módulo de Extensão" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -2279,11 +2456,11 @@ msgstr "" "extensão .pyd) para extensões Python no Windows ou um arquivo de classe Java " "para extensões Jython." -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "Known Good Set (KGS)" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -2298,11 +2475,11 @@ msgstr "" "usado por frameworks e kits de ferramentas que são compostos de várias " "distribuições individuais." -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "Pacote de Importação" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." @@ -2310,23 +2487,30 @@ msgstr "" "Um módulo Python que pode conter outros módulos ou recursivamente, outros " "pacotes." -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 +#, fuzzy +#| msgid "" +#| "An import package is more commonly referred to with the single word " +#| "\"package\", but this guide will use the expanded term when more clarity " +#| "is needed to prevent confusion with a :term:`Distribution Package` which " +#| "is also commonly called a \"package\"." msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" "Um pacote de importação é mais comumente referido com a única palavra " "\"pacote\", mas este guia usará o termo expandido quando mais clareza for " "necessária para evitar confusão com um :term:`Pacote de Distribuição` que " "também é comumente chamado de \"pacote\" ." -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Módulo" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." @@ -2334,11 +2518,11 @@ msgstr "" "A unidade básica de reutilização de código em Python, existindo em um dos " "dois tipos: :term:`Módulo Puro` ou :term:`Módulo de Extensão`." -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "Índice de Pacotes" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." @@ -2346,11 +2530,11 @@ msgstr "" "Um repositório de distribuições com uma interface web para automatizar " "descoberta e consumo de :term:`pacotes `." -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "Índice Por Projeto" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " @@ -2360,11 +2544,11 @@ msgstr "" "term:`Projeto` específico como o índice preferido ou necessário para " "resolver dependências desse projeto." -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Projeto" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " @@ -2374,7 +2558,7 @@ msgstr "" "outros recursos, ou alguma combinação dos mesmos que se destina a ser " "empacotado em uma :term:`Distribuição `." -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2388,7 +2572,7 @@ msgstr "" "que contém um arquivo :term:`pyproject.toml`, :term:`setup.py` ou :term:" "`setup.cfg` na raiz do diretório fonte do projeto." -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2400,7 +2584,7 @@ msgstr "" "`Lançamentos `, e cada lançamento pode incluir uma ou mais :term:" "`distribuições `." -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -2412,11 +2596,11 @@ msgstr "" "É possível instalar uma distribuição do projeto \"foo\" e fazer com que ele " "forneça um pacote importável apenas como \"bar\"." -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Módulo Puro" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." @@ -2424,11 +2608,11 @@ msgstr "" "Um :term:`Módulo` escrito em Python e contido em um único arquivo ``.py`` (e " "possivelmente arquivos ``.pyc`` e/ou ``.pyo`` associados)." -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "Python Packaging Authority (PyPA)" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2444,11 +2628,11 @@ msgstr "" "sig `_ e " "`o fórum Discourse do Python `__." -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "Python Package Index (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " @@ -2458,11 +2642,11 @@ msgstr "" "comunidade Python. Está aberto a todos os desenvolvedores Python para " "consumir e distribuir suas distribuições." -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." @@ -2472,22 +2656,22 @@ msgstr "" "Index (PyPI)`. Ele substituiu o nome de domínio do índice legado, ``pypi." "python.org``, em 2017. Ele é tornado possível pelo :ref:`warehouse`." -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" "O arquivo de especificação agnóstica de ferramenta para :term:`Projetos " "`. Definido na :pep:`518`." -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "Lançamento" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." @@ -2495,7 +2679,7 @@ msgstr "" "Um snapshot de um :term:`Projeto` em um determinado ponto no tempo, denotado " "por um identificador de versão." -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2507,11 +2691,11 @@ msgstr "" "projeto foi lançada, ele pode estar disponível em um formato de distribuição " "fonte e um formato de distribuição de instalador do Windows." -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "Requisito" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2525,17 +2709,23 @@ msgstr "" "podem ser consideradas um \"requisito\". Para obter mais informações, " "consulte a referência de :ref:`pip:pip install`." -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "Especificador de Requisitos" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 +#, fuzzy +#| msgid "" +#| "A format used by :ref:`pip` to install packages from a :term:`Package " +#| "Index`. For an EBNF diagram of the format, see the `pkg_resources." +#| "Requirement `_ entry in the :ref:`setuptools` docs. For " +#| "example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +#| "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" "Um formato usado por :ref:`pip` para instalar pacotes de um :term:`Índice de " @@ -2560,12 +2750,12 @@ msgstr "" "documentação :ref:`pip` em :ref:`pip:Requirements Files`." #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2597,12 +2787,6 @@ msgid "Source Distribution (or \"sdist\")" msgstr "Distribuição Fonte (ou \"sdist\")" #: ../source/glossary.rst:240 -#, fuzzy -#| msgid "" -#| "A :term:`distribution ` format (usually generated " -#| "using ``python setup.py sdist``) that provides metadata and the essential " -#| "source files needed for installing by a tool like :ref:`pip`, or for " -#| "generating a :term:`Built Distribution`." msgid "" "A :term:`distribution ` format (usually generated " "using ``python -m build --sdist``) that provides metadata and the essential " @@ -2610,7 +2794,7 @@ msgid "" "generating a :term:`Built Distribution`." msgstr "" "Um formato de :term:`distribuição ` (geralmente gerado " -"usando ``python setup.py sdist``) que fornece metadados e os arquivos-fonte " +"usando ``python -m build sdist``) que fornece metadados e os arquivos-fonte " "essenciais necessários para a instalação por uma ferramenta como :ref:`pip`, " "ou para gerar uma :term:`Distribuição Construída `." @@ -2631,13 +2815,6 @@ msgid "Version Specifier" msgstr "Especificador de Versão" #: ../source/glossary.rst:254 -#, fuzzy -#| msgid "" -#| "The version component of a :term:`Requirement Specifier`. For example, " -#| "the \">=1.3\" portion of \"foo>=1.3\". :pep:`440` contains a :pep:`full " -#| "specification <440#version-specifiers>` of the specifiers that Python " -#| "packaging currently supports. Support for PEP440 was implemented in :ref:" -#| "`setuptools` v8.0 and :ref:`pip` v6.0." msgid "" "The version component of a :term:`Requirement Specifier`. For example, the " "\">=1.3\" portion of \"foo>=1.3\". Read the :ref:`Version specifier " @@ -2646,10 +2823,11 @@ msgid "" "was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0." msgstr "" "O componente de versão de um :term:`Especificador de Requisitos `. Por exemplo, a parte \">=1.3\" de \"foo>=1.3\". A :pep:`440` " -"contém uma :pep:`especificação completa <440#version-specifiers>` dos " -"especificadores que o pacote Python oferece suporte atualmente. O suporte " -"para PEP440 foi implementado em :ref:`setuptools` v8.0 e :ref:`pip` v6.0." +"Specifier>`. Por exemplo, a parte \">=1.3\" de \"foo>=1.3\". Leia a :ref:" +"`especificação de especificador de versão ` para a " +"especificação completa dos especificadores que o empacotamento do Python " +"oferece suporte atualmente. O suporte para esta especificação foi " +"implementado no :ref:`setuptools` v8.0 e no :ref:`pip` v6.0." #: ../source/glossary.rst:259 msgid "Virtual Environment" @@ -2785,8 +2963,13 @@ msgstr "" "muito baixado, não significa que ele seja ruim!" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 +#, fuzzy +#| msgid "" +#| "In short, because it's value is low for various reasons, and the " +#| "tradeoffs required to make it work are high, it has been not an effective " +#| "use of limited resources." msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2877,14 +3060,14 @@ msgid "Column" msgstr "Coluna" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Descrição" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Exemplos" @@ -3289,8 +3472,7 @@ msgstr "" "O projeto `pandas-gbq`_ permite acessar resultados de pesquisa com `Pandas`_." #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "Referências" @@ -3539,6 +3721,16 @@ msgid "Packaging and distributing projects" msgstr "Empacotando e distribuindo projetos" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2013-12-08" +msgid "2023-12-14" +msgstr "2013-12-08" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -3552,7 +3744,7 @@ msgstr "" "projects`. Ele ainda assume que você já está familiarizado com o conteúdo da " "página :doc:`/tutorials/installing-packages`." -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " @@ -3562,13 +3754,7 @@ msgstr "" "projetos Python como um todo. Por exemplo, ele não fornece orientação ou " "recomendações de ferramentas para controle de versão, documentação ou teste." -#: ../source/guides/distributing-packages-using-setuptools.rst:17 -#, fuzzy -#| msgid "" -#| "For more reference material, see :std:doc:`Building and Distributing " -#| "Packages ` in the :ref:`setuptools` docs, but note that " -#| "some advisory content there may be outdated. In the event of conflicts, " -#| "prefer the advice in the Python Packaging User Guide." +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -3576,15 +3762,16 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" "Para mais material de referência, veja :std:doc:`Construindo e Distribuindo " -"Pacotes ` na documentação :ref:`setuptools`, mas note que " -"alguns conteúdos de aviso podem estar desatualizados. No caso de conflitos, " -"dê preferência ao conselho do Guia de Usuário para Empacotamento de Python." +"Pacotes ` na documentação :ref:`setuptools`, mas " +"note que alguns conteúdos de aviso podem estar desatualizados. No caso de " +"conflitos, dê preferência ao conselho do Guia de Usuário para Empacotamento " +"de Python." -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "Requisitos para empacotamento e distribuição" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." @@ -3592,11 +3779,11 @@ msgstr "" "Primeiro, certifique-se de que você já cumpriu os :ref:`requisitos para " "instalação de pacotes `." -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "Instale \"twine\" [1]_:" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " @@ -3606,15 +3793,15 @@ msgstr "" "Package>` do seu projeto para o :term:`PyPI ` " "(veja :ref:`abaixo `)." -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "Configurando seu projeto" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "Arquivos iniciais" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_ no `projeto de exemplo PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr ":file:`setup.py` tem duas funções principais:" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -3644,7 +3831,7 @@ msgstr "" "detalhes específicos do seu projeto são definidos. Os argumentos mais " "relevantes são explicados em :ref:`a seção abaixo de `." -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." @@ -3654,7 +3841,7 @@ msgstr "" "a tarefas de empacotamento. Para obter uma lista dos comandos disponíveis, " "execute ``python3 setup.py --help-commands``." -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ no `projeto de exemplo " "PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rst / README.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText `_ também são suportadas (veja o argumento :ref:" "`long_description_content_type ` do ``setup()``)." -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_ do `projeto de exemplo PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -3716,11 +3903,11 @@ msgstr "" "arquivo leia-me em :file:`MANIFEST.in`. Caso contrário, inclua para ser " "explícito." -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -3733,7 +3920,7 @@ msgstr "" "`MANIFEST.in`, incluindo uma lista do que é incluído por padrão, consulte \":" "ref:`Using MANIFEST.in`\"." -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3745,16 +3932,16 @@ msgstr "" "seu arquivo de manifesto, uma vez que todos os arquivos necessários foram " "incluídos pelo :ref:`setuptools` 43.0.0 e mais recentes." -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr ":file:`MANIFEST.in` não afeta distribuições binárias como wheels." -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3770,7 +3957,7 @@ msgstr "" "escolher, você pode usar recursos como `Escolha uma licença do GitHub " "`_ ou consultar um advogado." -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_ do `projeto de exemplo PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " @@ -3794,7 +3981,7 @@ msgstr "" "pacotes Python em um único pacote de nível superior que tem o mesmo :ref:" "`name ` do seu projeto, ou algo muito próximo." -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " @@ -3804,11 +3991,11 @@ msgstr "" "pypa/sampleproject/tree/main/src/sample>`_ que está incluído no `projeto de " "exemplo PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "Argumentos de setup()" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " @@ -3818,12 +4005,25 @@ msgstr "" "contém uma função global ``setup()``. Os argumentos nomeados para esta " "função são como os detalhes específicos do seu projeto são definidos." -#: ../source/guides/distributing-packages-using-setuptools.rst:156 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +#, fuzzy +#| msgid "" +#| "The most relevant arguments are explained below. Most of the snippets " +#| "given are taken from the `setup.py `_ contained in " +#| "the `PyPA sample project `_." msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" "Os argumentos mais relevantes são explicados a seguir. A maioria dos " "fragmentos fornecidos são retirados do `setup.py `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``name``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." msgstr "" -"Este é o nome do seu projeto, determinando como ele está listado no :term:" -"`PyPI `. Conforme :pep:`508`, nomes de projetos " -"válidos devem:" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" -"Consistir apenas em letras ASCII, dígitos, sublinhados (``_``), hífenes (``-" -"``) e/ou pontos (``.``) e" +"Veja :ref:`Escolhendo um esquema de versionamento ` para mais informações sobre maneiras de usar versões para " +"transmitir informações de compatibilidade para seus usuários." #: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "Começar e terminar com uma letra ou dígito ASCII." - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" -"A comparação de nomes de projetos não diferencia maiúsculas de minúsculas e " -"trata sequências arbitrariamente longas de sublinhados, hífenes e/ou pontos " -"como iguais. Por exemplo, se você registrar um projeto chamado ``cool-" -"stuff``, os usuários poderão baixá-lo ou declarar uma dependência dele " -"usando qualquer uma das seguintes formas de escrever::" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 -msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." -msgstr "" -"Esta é a versão atual do seu projeto, permitindo que seus usuários " -"determinem se têm ou não a versão mais recente e indiquem em quais versões " -"específicas eles testaram seu próprio software." - -#: ../source/guides/distributing-packages-using-setuptools.rst:201 -msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." -msgstr "" -"As versões são exibidas em :term:`PyPI ` para " -"cada lançamento se você publicar seu projeto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:204 -msgid "" -"See :ref:`Choosing a versioning scheme` for more information on ways to use " -"versions to convey compatibility information to your users." -msgstr "" -"Veja :ref:`Escolhendo um esquema de versionamento ` para mais informações sobre maneiras de usar versões para " -"transmitir informações de compatibilidade para seus usuários." - -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" -"Se o código do projeto em si precisa de acesso em tempo de execução para a " -"versão, a maneira mais simples é manter a versão em :file:`setup.py` e seu " -"código. Se você preferir não duplicar o valor, existem algumas maneiras de " -"gerenciar isso. Consulte a seção de tópicos avançados \":ref:`Fonte única da " -"versão `\"." - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "Da uma descrição curta e longa para seu projeto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" -"Esses valores serão exibidos no :term:`PyPI ` " -"se você publicar seu projeto. No ``pypi.org``, a interface do usuário exibe " -"``description`` no banner cinza e ``long_description`` na seção chamada " -"\"Descrição do Projeto\"." - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" -"``description`` também é exibido em listas de projetos. Por exemplo, ele é " -"visível nas páginas de resultados de pesquisa, como https://pypi.org/search/?" -"q=jupyter, nas listas da página inicial de projetos populares e novos " -"lançamentos e na lista de projetos que você mantém no perfil de sua conta " -"(como https://pypi.org/user/jaraco/)." - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -#, fuzzy -#| msgid "" -#| "A `content type `_ can be specified with the " -#| "``long_description_content_type`` argument, which can be one of ``text/" -#| "plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -#| "formatting, `reStructuredText (reST) `_, and the Github-" -#| "flavored Markdown dialect of `Markdown `_ respectively." -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" -"Um `tipo de conteúdo `_ pode ser especificado com o " -"argumento ``long_description_content_type``, que pode ser um de ``text/" -"plain``, ``text/x-rst`` ou ``text/markdown``, correspondendo a nenhuma " -"formatação, `reStructuredText (reST) `_, e o dialeto Markdown com " -"sabor do GitHub de `Markdown `_ respectivamente." - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "``url``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "Fornece o URL da página inicial do seu projeto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -#, fuzzy -msgid "``author``" -msgstr "author" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "Fornece detalhes sobre o autor." - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "``license``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" -"O argumento ``license`` não precisa indicar a licença sob a qual seu pacote " -"está sendo lançado, embora você possa opcionalmente fazer isso se desejar. " -"Se você estiver usando uma licença padrão bem conhecida, sua indicação " -"principal pode e deve ser por meio do argumento ``classifiers``. Existem " -"classificadores para todas as principais licenças de código aberto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" -"O argumento ``license`` é mais comumente usado para indicar diferenças de " -"licenças conhecidas ou para incluir sua própria licença exclusiva. Como " -"regra geral, é uma boa ideia usar uma licença padrão bem conhecida, tanto " -"para evitar confusão quanto porque algumas organizações evitam software cuja " -"licença não é aprovada." - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "``classifiers``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" -"Fornece uma lista de classificadores que categorizam seu projeto. Para obter " -"uma lista completa, consulte https://pypi.org/classifiers/." - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" -"Embora a lista de classificadores seja frequentemente usada para declarar " -"quais versões do Python um projeto suporta, essas informações são usadas " -"apenas para pesquisar e navegar por projetos no PyPI, não para instalar " -"projetos. Para realmente restringir em quais versões do Python um projeto " -"pode ser instalado, use o argumento :ref:`python_requires`." - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" -"Para evitar que um pacote seja enviado para PyPI, use o classificador " -"especial ``'Private :: Do Not Upload'``. PyPI sempre rejeitará pacotes com " -"classificadores começando com ``\"Private ::'``." - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "``keywords``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "Lista as palavras-chave que descrevem seu projeto." - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -#, fuzzy -msgid "``project_urls``" -msgstr "project_urls" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" -"Lista URLs relevantes adicionais sobre seu projeto. Este é o lugar para se " -"conectar a rastreadores de bugs, repositórios fontes ou onde oferecer " -"suporte ao desenvolvimento de pacotes. A string da chave é o texto exato que " -"será exibido no PyPI." - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 msgid "``packages``" msgstr "``packages``" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -4128,11 +4060,11 @@ msgstr "" "encontrar apenas os pacotes fornecidos. Use o argumento nomeado ``exclude`` " "para omitir pacotes que não devem ser lançados e instalados." -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "``py_modules``" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " @@ -4143,12 +4075,12 @@ msgstr "" "módulos (menos a extensão ``.py``) para fazer o :ref:`setuptools` ficar " "ciente deles." -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 #, fuzzy msgid "``install_requires``" msgstr "install_requires" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " @@ -4159,7 +4091,7 @@ msgstr "" "pelo :ref:`pip`, esta é a especificação que é usada para instalar suas " "dependências." -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." @@ -4168,67 +4100,11 @@ msgstr "" "`install_requires vs Arquivos de requisitos `." -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -#, fuzzy -msgid "``python_requires``" -msgstr "python_requires" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" -"Se o seu projeto só funciona em certas versões do Python, definir o " -"argumento ``python_requires`` para a string apropriada especificadora de " -"versão da :pep:`440` impedirá :ref:`pip` de instalar o projeto em outras " -"versões do Python. Por exemplo, se seu pacote for apenas para Python 3+, " -"escreva::" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" -"Se o seu pacote for para Python 2.6, 2.7 e todas as versões do Python 3 " -"começando com 3.3, escreva::" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "E por aí vai." - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" -"O suporte para esse recurso é relativamente recente. As distribuições de " -"código-fonte e wheels do seu projeto (veja :ref:`Empacotando seu projeto " -"`) devem ser construídas usando pelo menos a versão " -"24.2.0 do :ref:`setuptools` para que o argumento ``python_requires`` seja " -"reconhecido e os metadados apropriados gerados." - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" -"Além disso, apenas as versões 9.0.0 e superiores do :ref:`pip` reconhecem os " -"metadados de ``python_requires``. Usuários com versões anteriores do pip " -"serão capazes de baixar e instalar projetos em qualquer versão do Python, " -"independentemente dos valores de ``python_requires`` dos projetos." - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "``package_data``" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -4242,7 +4118,7 @@ msgstr "" "documentação que pode ser do interesse dos programadores que usam o pacote. " "Esses arquivos são chamados de \"dados do pacote\"." -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " @@ -4252,7 +4128,7 @@ msgstr "" "caminhos relativos que devem ser copiados para o pacote. Os caminhos são " "interpretados como relativos ao diretório que contém o pacote." -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." @@ -4261,11 +4137,11 @@ msgstr "" "` da :std:doc:`documentação do setuptools " "`." -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "``data_files``" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -4280,7 +4156,7 @@ msgstr "" "precisar instalar arquivos que são usados por outros programas, que podem " "não ter conhecimento dos pacotes Python." -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -4300,19 +4176,15 @@ msgstr "" "usuário). Cada nome de arquivo em ``files`` é interpretado em relação ao " "script :file:`setup.py` no topo da distribuição do código-fonte do projeto." -#: ../source/guides/distributing-packages-using-setuptools.rst:484 -#, fuzzy -#| msgid "" -#| "For more information see the distutils section on :ref:`Installing " -#| "Additional Files `." +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" "Para obter mais informações, consulte a seção distutils em :ref:`Instalando " -"arquivos adicionais `." +"arquivos adicionais `." -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -4324,96 +4196,34 @@ msgstr "" "Alternativamente, se você deve usar ``python setup.py``, então você precisa " "passar a opção ``--old-and-unmanageable``." -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 #, fuzzy msgid "``scripts``" msgstr "scripts" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 -#, fuzzy -#| msgid "" -#| "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " -#| "the recommended approach to achieve cross-platform compatibility is to " -#| "use :ref:`console_scripts` entry points (see below)." +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " "the recommended approach to achieve cross-platform compatibility is to use :" "ref:`console_scripts` entry points (see below)." msgstr "" -"Embora ``setup()`` tenha suporte a uma palavra-chave :ref:`scripts ` para apontar para scripts pré-fabricados para " -"instalar, o recomendado A abordagem para obter compatibilidade entre " -"plataformas é usar pontos de entrada :ref:`console_scripts` (veja abaixo)." - -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" -msgstr "``entry_points``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." -msgstr "" -"Use esta palavra-chave para especificar quaisquer plugins que seu projeto " -"fornece para quaisquer pontos de entrada nomeados que podem ser definidos " -"por seu projeto ou outros dos quais você depende." - -#: ../source/guides/distributing-packages-using-setuptools.rst:517 -msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" -"Para obter mais informações, consulte a seção sobre :ref:`Comportamento de " -"Publicidade ` da " -"documentação do :ref:`setuptools`." - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" -"O ponto de entrada mais comumente usado é \"console_scripts\" (veja abaixo)." +"Embora ``setup()`` tenha suporte a uma palavra-chave :ref:`scripts " +"` para apontar para scripts pré-" +"fabricados para instalar, o recomendado A abordagem para obter " +"compatibilidade entre plataformas é usar pontos de entrada :ref:" +"`console_scripts` (veja abaixo)." -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -#, fuzzy -msgid "``console_scripts``" -msgstr "console_scripts" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" -"Use :ref:`pontos de entrada ` de ``console_script`` para registrar suas interfaces de script. " -"Você pode então deixar o conjunto de ferramentas lidar com o trabalho de " -"transformar essas interfaces em scripts reais [2]_. Os scripts serão gerados " -"durante a instalação do seu :term:`distribuição `." - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" -"Para mais informações, veja :doc:`Entry Points ` (pontos de entrada, em português) da :doc:`documentação do " -"setuptools `." - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 +#: ../source/guides/distributing-packages-using-setuptools.rst:295 msgid "Choosing a versioning scheme" msgstr "Escolhendo um esquema de versionamento" -#: ../source/guides/distributing-packages-using-setuptools.rst:552 +#: ../source/guides/distributing-packages-using-setuptools.rst:298 msgid "Standards compliance for interoperability" msgstr "Conformidade de padrões para interoperabilidade" -#: ../source/guides/distributing-packages-using-setuptools.rst:554 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" "Different Python projects may use different versioning schemes based on the " "needs of that particular project, but all of them are required to comply " @@ -4427,11 +4237,11 @@ msgstr "" "version-identifiers>` flexível especificado na :pep:`440` para serem " "suportados em ferramentas e bibliotecas como ``pip`` e ``setuptools``." -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "Aqui estão alguns exemplos de números de versão compatíveis::" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -4443,15 +4253,15 @@ msgstr "" "`normalização de versão <440#normalization>` que mapeia grafias variantes de " "diferentes números de versão para uma forma canônica padronizada." -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "Opções de esquema" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "Versionamento semântico (preferencial)" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " @@ -4461,7 +4271,7 @@ msgstr "" "em `Versionamento semântico `_, mas adota uma abordagem " "diferente para lidar com pré-lançamentos e metadados de compilação." -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" @@ -4469,11 +4279,11 @@ msgstr "" "A essência do versionamento semântico é um esquema de numeração MAIOR.MENOR." "MANUTENÇÃO de 3 partes, onde o autor do projeto incrementa:" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "Versão PRINCIPAL quando eles fazem alterações de API incompatíveis," -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" @@ -4481,13 +4291,13 @@ msgstr "" "Versão MENOR quando adicionam funcionalidade de maneira compatível com " "versões anteriores, e" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" "Versão MANUTENÇÃO quando eles fazem correções de bugs compatíveis com " "versões anteriores." -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -4499,7 +4309,7 @@ msgstr "" "release>`, onde ``name ~= X.Y`` requer pelo menos a versão X.Y, mas também " "permite qualquer versão posterior com uma versão PRINCIPAL correspondente." -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." @@ -4507,11 +4317,11 @@ msgstr "" "Projetos Python que adotam versões semânticas devem obedecer às cláusulas " "1-8 da `especificação de Versionamento Semântico 2.0.0 `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "Versionamento baseado em data" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " @@ -4522,7 +4332,7 @@ msgstr "" "processo de descontinuidade que fornece avisos para vários lançamentos antes " "da remoção de um recurso." -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " @@ -4532,7 +4342,7 @@ msgstr "" "dizer quantos anos o conjunto de recursos básicos de uma determinada versão " "recebe apenas o número da versão." -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." @@ -4540,11 +4350,11 @@ msgstr "" "Os números de versão para projetos baseados em data normalmente assumem a " "forma de ANO.MÊS (por exemplo, ``12.04``, ``15.10``)." -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "Versionamento serial" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." @@ -4552,7 +4362,7 @@ msgstr "" "Este é o esquema de versionamento mais simples possível e consiste em um " "único número que é incrementado a cada versão." -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " @@ -4563,11 +4373,11 @@ msgstr "" "números de versão serial transmitem pouca ou nenhuma informação sobre " "compatibilidade com versões anteriores da API." -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "Esquemas híbridos" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -4580,11 +4390,11 @@ msgstr "" "aproximada de um lançamento, mas não se compromete com uma cadência de " "lançamento particular dentro do ano." -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "Versionamento de pré-lançamento" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" @@ -4592,24 +4402,24 @@ msgstr "" "Independentemente do esquema de versionamento base, os pré-lançamentos para " "uma determinada versão final podem ser publicados como:" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "zero ou mais versões dev (denotadas com um sufixo \".devN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "zero ou mais versões alfa (denotadas com um sufixo \".aN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "zero ou mais versões beta (denotadas com um sufixo \".bN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" "zero ou mais candidatos a lançamento (denotados com um sufixo \".rcN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." @@ -4617,12 +4427,12 @@ msgstr "" "``pip`` e outros instaladores de pacotes Python modernos ignoram os pré-" "lançamentos por padrão ao decidir quais versões de dependências instalar." -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "Identificadores de versão local" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -4639,7 +4449,7 @@ msgstr "" "destinadas à publicação, ou variantes modificadas de uma versão mantida por " "um redistribuidor." -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" @@ -4647,11 +4457,11 @@ msgstr "" "Um identificador de versão local assume a forma ``+``. Por exemplo::" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "Trabalhando em \"modo de desenvolvimento\"" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -4665,7 +4475,7 @@ msgstr "" "projetos instalados como editáveis serão refletidas na próxima vez que um " "processo de interpretador for iniciado." -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" @@ -4673,7 +4483,7 @@ msgstr "" "Para instalar um pacote Python no modo \"editável\"/\"desenvolvedor\" mude o " "diretório para a raiz do diretório do projeto e execute:" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -4689,7 +4499,7 @@ msgstr "" "``install_requires`` e quaisquer scripts declarados com ``console_scripts``. " "As dependências serão instaladas no modo usual e não editável." -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -4701,7 +4511,7 @@ msgstr "" "você deseja \"bar\" instalado do VCS no modo editável, então você poderia " "construir um arquivo de requisitos como::" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " @@ -4711,7 +4521,7 @@ msgstr "" "segunda linha substitui a dependência \"bar\", de modo que seja preenchida a " "partir do VCS, não PyPI." -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " @@ -4721,7 +4531,7 @@ msgstr "" "editável, o arquivo de requisitos deve ser semelhante a este, com os " "caminhos locais no topo do arquivo::" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -4736,31 +4546,25 @@ msgstr "" "instalações de VCS, consulte a seção :ref:`VCS Support ` da " "documentação do pip." -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" "Por último, se você não deseja instalar nenhuma dependência, pode executar:" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 -#, fuzzy -#| msgid "" -#| "For more information, see the :doc:`Development Mode ` section of the :doc:`setuptools docs " -#| "`." +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" "Para mais informações, veja a seção :doc:`Development Mode ` na :doc:`documentação do setuptools " -"`.." +"userguide/development_mode>` na documentação do :ref:`setuptools`." -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "Empacotando seu projeto" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -4772,7 +4576,7 @@ msgstr "" "`Distribuição ` (também conhecida como \":term:`Pacote " "`\") para seu projeto." -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" @@ -4780,11 +4584,11 @@ msgstr "" "Antes de compilar wheels e sdists para seu projeto, você precisará instalar " "o pacote ``build``:" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "Distribuições fontes" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" @@ -4792,7 +4596,7 @@ msgstr "" "Minimamente, você deve criar uma :term:`Distribuição Fonte `:" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -4806,11 +4610,11 @@ msgstr "" "extensões), ainda envolve uma etapa de construção para construir os " "metadados de instalação de :file:`setup.py` e/ou :file:`setup.cfg`." -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "Wheels" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -4823,7 +4627,7 @@ msgstr "" "substancialmente mais rápido para o usuário final do que instalar a partir " "de uma distribuição original." -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." @@ -4831,7 +4635,7 @@ msgstr "" "Se o seu projeto for puro Python, você criará uma :ref:`\"Wheel de Python " "Puro\" (consulte a seção abaixo) `." -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." @@ -4840,7 +4644,7 @@ msgstr "" "chamado de :ref:`*Wheel de Plataforma* (veja a seção abaixo) `." -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " @@ -4850,7 +4654,7 @@ msgstr "" "C, você deve criar o que é chamado de *Wheel Universal* adicionando o " "seguinte ao seu arquivo :file:`setup.cfg`:" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." @@ -4858,11 +4662,11 @@ msgstr "" "Use esta configuração apenas se o seu projeto não tiver extensões C *e* " "tiver suporte ao Python 2 e 3." -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "Wheels de Puro Python" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." @@ -4870,12 +4674,12 @@ msgstr "" "*Wheels de Python Puro* contêm nenhuma extensão compilada e, portanto, só " "exigem um único wheel Python." -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "Para construir o wheel:" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " @@ -4885,7 +4689,7 @@ msgstr "" "wheel cujo nome pode ser usado em qualquer instalação do Python 3. Para " "obter detalhes sobre a nomenclatura de arquivos wheel, consulte :pep:`425`." -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." @@ -4894,11 +4698,11 @@ msgstr "" "os dois arquivos para você; isso é útil quando você não precisa de vários " "wheels." -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "Wheels de Plataforma" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." @@ -4907,7 +4711,7 @@ msgstr "" "plataforma, como Linux, macOS ou Windows, geralmente em razão de conter " "extensões compiladas." -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " @@ -4917,7 +4721,7 @@ msgstr "" "wheel cujo nome só pode ser usado na plataforma em que foi construído. Para " "obter detalhes sobre a nomenclatura de arquivos wheel, consulte :pep:`425`." -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " @@ -4927,11 +4731,11 @@ msgstr "" "envios de wheels de plataforma do Windows, macOS e da ABI multidistro " "``manylinux*``. Detalhes sobre o último estão definidos em :pep:`513`." -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "Enviando seu Projeto para PyPI" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " @@ -4941,7 +4745,7 @@ msgstr "" "diretório ``dist/`` foi criado no diretório raiz do seu projeto. É onde você " "encontrará seus arquivos de distribuição para enviar." -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -4954,7 +4758,7 @@ msgstr "" "precisará reconstruir esses arquivos novamente antes de distribuir as " "alterações para PyPI." -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -4966,7 +4770,7 @@ msgstr "" "uma base semirregular. Veja :ref:`using-test-pypi` sobre como definir sua " "configuração para usá-lo." -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -4981,7 +4785,7 @@ msgstr "" "Python, permitindo que seu nome de usuário e senha sejam interceptados " "durante a transmissão." -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -4998,11 +4802,11 @@ msgstr "" "pode fazer isso executando :std:doc:`twine check ` em todos arquivos " "do seu pacote:" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Criar uma conta" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `. Você pode criar uma conta `usando o formulário no " "site do PyPI `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." @@ -5020,7 +4824,7 @@ msgstr "" "Agora você criará um `token de API`_ do PyPI para que possa enviar o seu " "projeto com segurança." -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " @@ -5030,7 +4834,7 @@ msgstr "" "API`_; não limite seu escopo a um projeto específico, já que você está " "criando um novo projeto." -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" @@ -5038,7 +4842,7 @@ msgstr "" "**Não feche a página antes de copiar e salvar o token -- você não verá o " "token novamente.**" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" @@ -5046,24 +4850,24 @@ msgstr "" "Para evitar ter que copiar e colar o token toda vez que você enviar, você " "pode criar um arquivo :file:`$HOME/.pypirc`:" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "**Esteja ciente de que isso armazena seu token em texto simples.**" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" "Para mais detalhes, veja a :ref:`especificação ` do :file:`.pypirc`." -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "Enviar suas distribuições" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." @@ -5071,7 +4875,7 @@ msgstr "" "Assim que tiver uma conta, você pode enviar suas distribuições para o :term:" "`PyPI ` usando :ref:`twine`." -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " @@ -5081,7 +4885,7 @@ msgstr "" "já existir ou não no PyPI -- se ainda não existir, será criado " "automaticamente quando a primeira versão for carregada." -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." @@ -5089,7 +4893,7 @@ msgstr "" "Para a segunda versão e as subsequentes, PyPI requer apenas que o número da " "versão da nova versão seja diferente de todas as versões anteriores." -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -5101,7 +4905,7 @@ msgstr "" "nome do seu projeto que você enviou. O seu projeto pode demorar um ou dois " "minutos para aparecer no site." -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -5113,19 +4917,6 @@ msgstr "" "as instalações de usuário o comportamento padrão `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" -"Especificamente, a abordagem \"console_script\" gera arquivos ``.exe`` no " -"Windows, que são necessários por causa dos arquivos ``.exe`` de casos " -"especiais do sistema operacional. Recursos de execução de script como " -"``PATHEXT`` e o :pep:`Inicializador do Python para Windows <397>` permitem " -"que scripts sejam usados em muitos casos, mas não em todos." - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "Descartando suporte para versões mais antigas do Python" @@ -5254,10 +5045,8 @@ msgid "Steps:" msgstr "Passos:" #: ../source/guides/dropping-older-python-versions.rst:74 -#, fuzzy -#| msgid "`setuptools` version should be above 24.0.0." msgid "``setuptools`` version should be above 24.0.0." -msgstr "A versão do `setuptools` deve ser superior a 24.0.0." +msgstr "A versão do ``setuptools`` deve ser superior a 24.0.0." #: ../source/guides/dropping-older-python-versions.rst:77 msgid "2. Specify the version ranges for supported Python distributions" @@ -5273,19 +5062,12 @@ msgstr "" "menos Python 3. Ou Python 2.7, 3.4 e superior." #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +#, fuzzy +#| msgid "Examples::" +msgid "Examples:" msgstr "Exemplos::" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " @@ -5295,11 +5077,11 @@ msgstr "" "seu script :file:`setup.py`. Isso irá inserir os valores de metadados " "``Requires-Python`` com base no argumento fornecido em ``python_requires``." -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "3. Validando o Metadata antes de publicar" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." @@ -5307,30 +5089,25 @@ msgstr "" "Dentro de um pacote fonte Python (o arquivo zip ou tar-gz que você baixou) " "está um arquivo de texto chamado PKG-INFO." -#: ../source/guides/dropping-older-python-versions.rst:105 -#, fuzzy -#| msgid "" -#| "This file is generated by Distutils or :ref:`setuptools` when it " -#| "generates the source package. The file contains a set of keys and values, " -#| "the list of keys is part of the PyPa standard metadata format." +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -"Este arquivo é gerado pelo Distutils ou :ref:`setuptools` quando ele gera o " -"pacote fonte. O arquivo contém um conjunto de chaves e valores, a lista de " -"chaves faz parte do formato de metadados padrão do PyPa." +"Este arquivo é gerado pelo :ref:`distutils` ou :ref:`setuptools` quando ele " +"gera o pacote fonte. O arquivo contém um conjunto de chaves e valores, a " +"lista de chaves faz parte do formato de metadados padrão do PyPa." -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "Você pode ver o conteúdo do arquivo gerado assim:" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "Valide que o seguinte está no lugar, antes de publicar o pacote:" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." @@ -5338,18 +5115,18 @@ msgstr "" "Se você atualizou corretamente, o valor de Metadata-Version deve ser 1.2 ou " "superior." -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" "O campo Requires-Python está definido e corresponde a sua especificação no " "setup.py." -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "4. Usando Twine para publicar" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." @@ -5357,16 +5134,16 @@ msgstr "" "Twine tem uma série de vantagens, além de ser mais rápido, agora é o método " "suportado para publicação de pacotes." -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" "Certifique-se de estar usando a versão mais recente do Twine, pelo menos 1.9." -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "Descartando uma versão Python" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." @@ -5375,12 +5152,12 @@ msgstr "" "fazer uma atualização adicional removendo esse tempo de execução Python do " "suporte." -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" "Deve ser feito nesta ordem para que o alternativa automatizada funcione." -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." @@ -5388,7 +5165,7 @@ msgstr "" "Por exemplo, você publicou o Requires-Python: \">=2.7\" como a versão 1.0.0 " "do seu pacote." -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -5405,11 +5182,17 @@ msgid "Hosting your own simple repository" msgstr "Hospedando seu próprio repositório simples" #: ../source/guides/hosting-your-own-index.rst:8 +#, fuzzy +#| msgid "" +#| "If you wish to host your own simple repository [1]_, you can either use a " +#| "software package like :doc:`devpi ` or you can use simply " +#| "create the proper directory structure and use any web server that can " +#| "serve static files and generate an autoindex." msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" "Se você deseja hospedar seu próprio repositório simples [1]_, você pode usar " "um pacote de software como :doc:`devpi ` ou você pode usar " @@ -5801,7 +5584,7 @@ msgstr "" "ferramentas padrão ``pip`` e ``virtualenv``." #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "Spack" @@ -5961,6 +5744,7 @@ msgstr "" "aplicações do pacote de qualquer lugar." #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "Por exemplo:" @@ -5993,8 +5777,8 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "Para ver a lista completa de comandos pipx oferece, execute:" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." -msgstr "Você pode aprender mais sobre pipx em https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "Você pode aprender mais sobre pipx em https://pipx.pypa.io/." #: ../source/guides/installing-using-linux-tools.rst:5 msgid "Installing pip/setuptools/wheel with Linux Package Managers" @@ -6205,10 +5989,8 @@ msgstr "" "conforme descrito." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 -#, fuzzy -#| msgid "Installing packages using pip and virtual environments" msgid "Install packages in a virtual environment using pip and venv" -msgstr "Instalando pacotes usando pip e ambientes virtuais" +msgstr "Instalar pacotes em um ambiente virtual usando pip e venv" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 msgid "" @@ -6216,50 +5998,45 @@ msgid "" "the standard library's virtual environment tool :ref:`venv` and install " "packages. The guide covers how to:" msgstr "" +"Este guia discute como criar e ativar um ambiente virtual usando a " +"ferramenta de ambiente virtual da biblioteca padrão :ref:`venv` e instalar " +"pacotes. O guia aborda como:" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 -#, fuzzy -#| msgid "Creating a virtual environment" msgid "Create and activate a virtual environment" -msgstr "Criando um ambiente virtual" +msgstr "Criar e ativar um ambiente virtual" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" -msgstr "" +msgstr "Preparar o pip" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 -#, fuzzy -#| msgid "Installing packages using pip and virtual environments" msgid "Install packages into a virtual environment using the ``pip`` command" -msgstr "Instalando pacotes usando pip e ambientes virtuais" +msgstr "Instalar pacotes em um ambinente virtual usando o comando ``pip``" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 -#, fuzzy -#| msgid "Using requirements files" msgid "Use and create a requirements file" -msgstr "Usando arquivos de requisitos" +msgstr "Usar e criar o arquivo de requisitos" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 msgid "" "This guide applies to supported versions of Python, currently 3.8 and higher." msgstr "" +"Este guia se aplica a versões suportadas do Python, atualmente 3.8 e " +"superior." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 -#, fuzzy -#| msgid "" -#| "This doc uses the term **package** to refer to a :term:`Distribution " -#| "Package` which is different from an :term:`Import Package` that which is " -#| "used to import modules in your Python source code." msgid "" "This guide uses the term **package** to refer to a :term:`Distribution " "Package`, which commonly is installed from an external host. This differs " "from the term :term:`Import Package` which refers to import modules in your " "Python source code." msgstr "" -"Este documento usa o termo **pacote** para se referir a um :term:`Pacote de " -"Distribuição` que é diferente de um :term:`Pacote de Importação` que é usado " -"para importar módulos em seu código-fonte do Python." +"Este guia usa o termo **pacote** para se referir a um :term:`Pacote de " +"Distribuição`, o qual é comumente instalado a partir de um host externo. Ele " +"é diferente do termo :term:`Pacote de Importação` que se refere a importar " +"módulos em seu código-fonte do Python." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 msgid "" @@ -6268,30 +6045,21 @@ msgid "" "your operating system's package manager to install Python, please ensure " "that Python is installed before proceeding with these steps." msgstr "" +"Este guia tem como pré-requisito que você esteja usando uma versão oficial " +"do Python obtida em . Se você estiver " +"usando o gerenciador de pacotes do seu sistema operacional para instalar o " +"Python, certifique-se de que o Python esteja instalado antes de prosseguir " +"com estas etapas." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 -#, fuzzy -#| msgid "Creating Virtual Environments" msgid "Create and Use Virtual Environments" -msgstr "Criando ambientes virtuais" +msgstr "Criar e usar ambientes virtuais" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 -#, fuzzy -#| msgid "Creating a virtual environment" msgid "Create a new virtual environment" -msgstr "Criando um ambiente virtual" +msgstr "Criar um novo ambiente virtual" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 -#, fuzzy -#| msgid "" -#| ":ref:`venv` (for Python 3) and :ref:`virtualenv` (for Python 2) allow you " -#| "to manage separate package installations for different projects. They " -#| "essentially allow you to create a \"virtual\" isolated Python " -#| "installation and install packages into that virtual installation. When " -#| "you switch projects, you can simply create a new virtual environment and " -#| "not have to worry about breaking the packages installed in the other " -#| "environments. It is always recommended to use a virtual environment while " -#| "developing Python applications." msgid "" ":ref:`venv` (for Python 3) allows you to manage separate package " "installations for different projects. It creates a \"virtual\" isolated " @@ -6300,56 +6068,48 @@ msgid "" "from the virtual environment since packages can be installed confidently and " "will not interfere with another project's environment." msgstr "" -":ref:`venv` (para Python 3) e :ref:`virtualenv` (para Python 2) permitem que " -"você gerencie instalações de pacotes separadas para projetos diferentes. " -"Eles essencialmente permitem que você crie uma instalação \"virtual\" " -"isolada do Python e instale pacotes nessa instalação virtual. Ao trocar de " -"projeto, você pode simplesmente criar um novo ambiente virtual e não precisa " -"se preocupar em quebrar os pacotes instalados nos outros ambientes. É sempre " -"recomendável usar um ambiente virtual ao desenvolver aplicações Python." +":ref:`venv` (para Python 3) permite gerenciar instalações de pacotes " +"separadas para projetos diferentes. Ele cria uma instalação Python " +"\"virtual\" e isolada. Ao alternar projetos, você pode criar um novo " +"ambiente virtual isolado de outros ambientes virtuais. Você se beneficia do " +"ambiente virtual, pois os pacotes podem ser instalados com segurança e não " +"interferirão no ambiente de outro projeto." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:45 msgid "" "It is recommended to use a virtual environment when working with third party " "packages." msgstr "" +"Recomenda-se usar um ambiente virtual ao trabalhar com pacotes de terceiros." #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 #, fuzzy #| msgid "" #| "To create a virtual environment, go to your project's directory and run " -#| "venv. If you are using Python 2, replace ``venv`` with ``virtualenv`` in " -#| "the below commands." +#| "``venv``. This will create a new virtual environment in a local folder ``." +#| "venv``:" msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" "Para criar um ambiente virtual, vá até o diretório do seu projeto e execute " -"venv. Se você estiver usando Python 2, substitua ``venv`` por ``virtualenv`` " -"nos comandos abaixo." +"``venv``. Isto criará um novo ambiente virtual em uma pasta local ``.venv``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 -#, fuzzy -#| msgid "" -#| "The second argument is the location to create the virtual environment. " -#| "Generally, you can just create this in your project and call it ``env``." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" "O segundo argumento é o local para criar o ambiente virtual. Geralmente, " -"você pode apenas criar isso em seu projeto e chamá-lo de ``env``." +"você pode apenas criar isso em seu projeto e chamá-lo de ``.venv``." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 -#, fuzzy -#| msgid "" -#| "venv will create a virtual Python installation in the ``env`` folder." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." -msgstr "venv irá criar uma instalação virtual Python na pasta ``env``." +msgstr "``venv`` irá criar uma instalação virtual Python na pasta ``.venv``." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." @@ -6357,19 +6117,11 @@ msgstr "" "Você deve excluir seu diretório de ambiente virtual de seu sistema de " "controle de versão usando ``.gitignore`` ou similar." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 -#, fuzzy -#| msgid "Activating a virtual environment" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" -msgstr "Ativando um ambiente virtual" +msgstr "Ativar um ambiente virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 -#, fuzzy -#| msgid "" -#| "Before you can start installing or using packages in your virtual " -#| "environment you'll need to *activate* it. Activating a virtual " -#| "environment will put the virtual environment-specific ``python`` and " -#| "``pip`` executables into your shell's ``PATH``." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -6377,116 +6129,91 @@ msgid "" "into your shell's ``PATH``." msgstr "" "Antes de começar a instalar ou usar pacotes em seu ambiente virtual, você " -"precisará *ativá-lo*. Ativar um ambiente virtual colocará os executáveis " -"``python`` e ``pip`` específicos do ambiente virtual no ``PATH`` de seu " -"shell." +"precisará ativá-lo, com ``activate``. Ativar um ambiente virtual colocará os " +"executáveis ``python`` e ``pip`` específicos do ambiente virtual no ``PATH`` " +"de seu shell." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 -#, fuzzy -#| msgid "" -#| "You can confirm you're in the virtual environment by checking the " -#| "location of your Python interpreter:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -"Você pode confirmar que está no ambiente virtual verificando a localização " -"do seu interpretador Python:" +"Para confirmar o ambiente virtual está ativado, verifique o local do seu " +"interpretador Python:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" +"Enquanto o ambiente virtual estiver ativo, o comando acima irá gerar um " +"caminho de arquivo que inclui o diretório ``.venv``, terminando com o " +"seguinte:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 -#, fuzzy -#| msgid "" -#| "As long as your virtual environment is activated pip will install " -#| "packages into that specific environment and you'll be able to import and " -#| "use packages in your Python application." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -"Contanto que seu ambiente virtual esteja ativado, pip instalará pacotes " -"naquele ambiente específico e você poderá importar e usar pacotes em sua " +"Enquanto um ambiente virtual estiver ativado, pip instalará pacotes naquele " +"ambiente específico. Isso permite que você importe e use pacotes em sua " "aplicação Python." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 -#, fuzzy -#| msgid "Activating a virtual environment" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" -msgstr "Ativando um ambiente virtual" +msgstr "Desativar um ambiente virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 -#, fuzzy -#| msgid "" -#| "If you want to switch projects or otherwise leave your virtual " -#| "environment, simply run:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -"Se você deseja trocar de projeto ou de outra forma deixar seu ambiente " -"virtual, basta executar:" +"Se você deseja trocar de projeto ou sair do seu ambiente virtual, desative o " +"ambiente com ``deactivate``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" +"Fechar seu shell desativará o ambiente virtual. Se você abrir uma nova " +"janela do shell e quiser usar o ambiente virtual, reative-o." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 -#, fuzzy -#| msgid "Activating a virtual environment" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" -msgstr "Ativando um ambiente virtual" +msgstr "Reativar um ambiente virtual" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 -#, fuzzy -#| msgid "" -#| "If you want to re-enter the virtual environment just follow the same " -#| "instructions above about activating a virtual environment. There's no " -#| "need to re-create the virtual environment." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -"Se você deseja entrar novamente no ambiente virtual, basta seguir as mesmas " -"instruções acima sobre como ativar um ambiente virtual. Não há necessidade " -"de recriar o ambiente virtual." +"Se você quiser reativar um ambiente virtual existente, siga as mesmas " +"instruções sobre como ativar um ambiente virtual. Não há necessidade de " +"criar um novo ambiente virtual." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 -#, fuzzy -#| msgid "" -#| ":ref:`pip` is the reference Python package manager. It's used to install " -#| "and update packages. You'll need to make sure you have the latest version " -#| "of pip installed." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" ":ref:`pip` é o gerenciador de pacotes de referência Python. É usado para " -"instalar e atualizar pacotes. Você precisará certificar-se de que possui a " -"versão mais recente do pip instalada." +"instalar e atualizar pacotes. Ele é usado para instalar e atualizar pacotes " +"em um ambiente virtual." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 -#, fuzzy -#| msgid "" -#| "The Python installers for Windows include pip. You can make sure that pip " -#| "is up-to-date by running:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -"Os instaladores do Python para Windows incluem pip. Você pode garantir que o " -"pip está atualizado usando:" +"Os instaladores de Python para macOS incluem pip. No Linux, você pode ter " +"que instalar um pacote adicional como ``python3-pip``. Você pode ter certeza " +"de que o pip está atualizado executando:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" @@ -6494,7 +6221,7 @@ msgstr "" "Depois disso, você deve ter a versão mais recente do pip instalado em seu " "site de usuário:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" @@ -6502,62 +6229,45 @@ msgstr "" "Os instaladores do Python para Windows incluem pip. Você pode garantir que o " "pip está atualizado usando:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "Depois disso, você deve ter a versão mais recente do pip:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 -#, fuzzy -#| msgid "Installing packages using pip and virtual environments" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" -msgstr "Instalando pacotes usando pip e ambientes virtuais" +msgstr "Instalar pacotes usando pip" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 -#, fuzzy -#| msgid "" -#| "As long as your virtual environment is activated pip will install " -#| "packages into that specific environment and you'll be able to import and " -#| "use packages in your Python application." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -"Contanto que seu ambiente virtual esteja ativado, pip instalará pacotes " -"naquele ambiente específico e você poderá importar e usar pacotes em sua " -"aplicação Python." +"Quando seu ambiente virtual estiver ativado, você poderá instalar pacotes. " +"Use o comando ``pip install`` para instalar pacotes." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 -#, fuzzy -#| msgid "Installing packages" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" -msgstr "Instalando pacotes" +msgstr "Instalar um pacote" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 -#, fuzzy -#| msgid "" -#| "Now that you're in your virtual environment you can install packages. " -#| "Let's install the `Requests`_ library from the :term:`Python Package " -#| "Index (PyPI)`:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -"Agora que você está em seu ambiente virtual, pode instalar pacotes. Vamos " -"instalar a biblioteca `Requests`_ do :term:`Python Package Index (PyPI)`:" +"Por exemplo, vamos instalar a biblioteca `Requests`_ do :term:`Python " +"Package Index (PyPI)`:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" "pip deve baixar solicitações e todas as suas dependências e instalá-los:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 -#, fuzzy -#| msgid "To install a specific version:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" -msgstr "Para instalar uma versão específica:" +msgstr "Instalar uma versão específica do pacote" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " @@ -6567,23 +6277,21 @@ msgstr "" "term:`especificadores de versão `. Por exemplo, " "para instalar uma versão específica do ``requests``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "Para instalar a versão ``2.x`` mais recente do requests:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" "Para instalar versões de pré-lançamento de pacotes, use o sinalizador ``--" "pre``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 -#, fuzzy -#| msgid "Installing extras" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" -msgstr "Instalando extras" +msgstr "Instalar extras" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" @@ -6591,25 +6299,19 @@ msgstr "" "Alguns pacotes possuem `extras`_ opcionais. Você pode dizer ao pip para " "instalá-los especificando o extra entre colchetes:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 -#, fuzzy -#| msgid "Installing from source" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" -msgstr "Instalando a partir do código-fonte" +msgstr "Instalar um pacote a partir do código-fonte" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 -#, fuzzy -#| msgid "" -#| "pip can install packages directly from their version control system. For " -#| "example, you can install directly from a git repository:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -"pip pode instalar pacotes diretamente de seu sistema de controle de versão. " -"Por exemplo, você pode instalar diretamente de um repositório git:" +"pip pode instalar um pacote diretamente de seu código-fonteseu. Por exemplo, " +"você pode instalar o código-fonte no diretório ``google-auth``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -6621,13 +6323,11 @@ msgstr "" "que as mudanças no diretório de código-fonte afetarão imediatamente o pacote " "instalado sem a necessidade de reinstalar:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 -#, fuzzy -#| msgid "Installing from version control systems" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" -msgstr "Instalando a partir de sistemas de controle de versão" +msgstr "Instalar a partir de sistemas de controle de versão" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" @@ -6635,7 +6335,7 @@ msgstr "" "pip pode instalar pacotes diretamente de seu sistema de controle de versão. " "Por exemplo, você pode instalar diretamente de um repositório git:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." @@ -6644,13 +6344,11 @@ msgstr "" "sintaxe, consulte a documentação do pip em :ref:`Suporte VCS `." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 -#, fuzzy -#| msgid "Installing from local archives" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" -msgstr "Instalando de arquivos locais" +msgstr "Instalar a partir de arquivos locais" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" @@ -6659,7 +6357,7 @@ msgstr "" "Distribuição` (um arquivo zip, wheel ou tar), você pode instalá-lo " "diretamente com pip:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " @@ -6669,7 +6367,7 @@ msgstr "" "dizer ao pip para procurar por pacotes lá e não usar o :term:`Python Package " "Index (PyPI)` de forma alguma:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " @@ -6679,13 +6377,11 @@ msgstr "" "conectividade limitada ou se quiser controlar estritamente a origem dos " "pacotes de distribuição." -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 -#, fuzzy -#| msgid "Installing from other Indexes" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" -msgstr "Instalando a partir de outros índices" +msgstr "Instalar a partir de outros índices de pacote" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" @@ -6693,7 +6389,7 @@ msgstr "" "Se você quiser baixar pacotes de um índice diferente do :term:`Python " "Package Index (PyPI)`, você pode usar o sinalizador ``--index-url``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " @@ -6703,12 +6399,12 @@ msgstr "" "um índice separado, você pode usar a sinalização ``--extra-index-url`` em " "seu lugar:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "Atualizando pacotes" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" @@ -6717,13 +6413,11 @@ msgstr "" "exemplo, para instalar a versão mais recente de ``requests`` e todas as suas " "dependências:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 -#, fuzzy -#| msgid "Using requirements files" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" -msgstr "Usando arquivos de requisitos" +msgstr "Usando um arquivo de requisitos" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " @@ -6734,7 +6428,7 @@ msgstr "" "Files>`. Por exemplo, você pode criar um arquivo :file:`requirements.txt` " "contendo:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" @@ -6742,11 +6436,11 @@ msgstr "" "E diga ao pip para instalar todos os pacotes neste arquivo usando o " "sinalizador ``-r``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "Congelando dependências" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" @@ -6754,34 +6448,31 @@ msgstr "" "Pip pode exportar uma lista de todos os pacotes instalados e suas versões " "usando o comando ``freeze``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "O que resultará em uma lista de especificadores de pacote, como:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 -#, fuzzy -#| msgid "" -#| "This is useful for creating :ref:`pip:Requirements Files` that can re-" -#| "create the exact versions of all packages installed in an environment." +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " "environment." msgstr "" -"Isso é útil para criar :ref:`pip:Requirements Files` que podem recriar as " -"versões exatas de todos os pacotes instalados em um ambiente." +"O comando ``pip freeze`` útil para criar :ref:`pip:Requirements Files` que " +"podem recriar as versões exatas de todos os pacotes instalados em um " +"ambiente." #: ../source/guides/installing-using-virtualenv.rst:2 -#, fuzzy -#| msgid "Installing packages using pip and virtual environments" msgid "Installing packages using virtualenv" -msgstr "Instalando pacotes usando pip e ambientes virtuais" +msgstr "Instalando pacotes usando virtualenv" #: ../source/guides/installing-using-virtualenv.rst:4 msgid "" "This guide discusses how to install packages using :ref:`pip` and :ref:" "`virtualenv`, a tool to create isolated Python environments." msgstr "" +"Este guia discute como instalar pacotes usando :ref:`pip` e :ref:" +"`virtualenv`, uma ferramenta para criar ambientes Python isolados." #: ../source/guides/installing-using-virtualenv.rst:8 msgid "" @@ -6789,6 +6480,9 @@ msgid "" "under development. Please refer to the :ref:`virtualenv` documentation for " "details on installation and usage." msgstr "" +"Este guia sobre como instalar pacotes e usar :ref:`virtualenv` está em " +"desenvolvimento. Consulte a documentação do :ref:`virtualenv` para detalhes " +"sobre instalação e uso." #: ../source/guides/installing-using-virtualenv.rst:13 msgid "" @@ -7241,13 +6935,11 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:6 msgid "How to modernize a ``setup.py`` based project?" -msgstr "" +msgstr "Como modernizar um projeto baseado em ``setup.py``?" #: ../source/guides/modernize-setup-py-project.rst:10 -#, fuzzy -#| msgid "pyproject.toml" msgid "Should ``pyproject.toml`` be added?" -msgstr "pyproject.toml" +msgstr "``pyproject.toml`` deve ser adicionado?" #: ../source/guides/modernize-setup-py-project.rst:12 msgid "" @@ -7256,11 +6948,17 @@ msgid "" "strongly recommended is the ``[build-system]`` table in :file:`pyproject." "toml`." msgstr "" +"Um arquivo :term:`pyproject.toml` é fortemente recomendado. A presença de um " +"arquivo :file:`pyproject.toml` em si não traz muita coisa. [#]_ O que é " +"realmente recomendado é a tabela ``[build-system]`` no :file:`pyproject." +"toml`." #: ../source/guides/modernize-setup-py-project.rst:16 msgid "" "Note that it has influence on the build isolation feature of pip, see below." msgstr "" +"Observe que isso tem influência no recurso de isolamento de construção do " +"pip, veja abaixo." #: ../source/guides/modernize-setup-py-project.rst:23 msgid "" @@ -7270,12 +6968,15 @@ msgid "" "deprecated and **MUST NOT** be run anymore, and their recommended " "replacement commands should be used instead:" msgstr "" +"Não, :file:`setup.py` pode existir em um projeto moderno baseado em :ref:" +"`setuptools`. O arquivo :term:`setup.py` é um arquivo de configuração válido " +"para setuptools que foi escrito em Python. No entanto, os seguintes comandos " +"for descontinuados e **NÃO DEVEM** ser mais executados, e seus comandos de " +"substituição recomendados devem ser usados:" #: ../source/guides/modernize-setup-py-project.rst:36 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m build``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python -m build``" #: ../source/guides/modernize-setup-py-project.rst:42 #: ../source/guides/modernize-setup-py-project.rst:66 @@ -7283,28 +6984,23 @@ msgstr "Sim (``python -m pip uninstall``)" #: ../source/guides/modernize-setup-py-project.rst:129 #: ../source/guides/modernize-setup-py-project.rst:221 msgid "For more details:" -msgstr "" +msgstr "Para mais detalhes:" #: ../source/guides/modernize-setup-py-project.rst:44 msgid ":ref:`setup-py-deprecated`" -msgstr "" +msgstr ":ref:`setup-py-deprecated`" #: ../source/guides/modernize-setup-py-project.rst:48 -#, fuzzy -#| msgid "Get started" msgid "Where to start?" -msgstr "Primeiros passos" +msgstr "Onde começar?" #: ../source/guides/modernize-setup-py-project.rst:50 -#, fuzzy -#| msgid "" -#| "Open :file:`pyproject.toml` and enter one of these ``[build-system]`` " -#| "tables:" msgid "" "The :term:`project` must contain a :file:`pyproject.toml` file at the root " "of its source tree that contains a ``[build-system]`` table like so:" msgstr "" -"Abra :file:`pyproject.toml` e insira uma destas tabelas ``[build-system]``:" +"O :term:`projeto` deve conter um arquivo :file:`pyproject.toml` na raiz de " +"sua árvore de fontes que contém uma tabela ``[build-system]`` como esta:" #: ../source/guides/modernize-setup-py-project.rst:60 msgid "" @@ -7312,36 +7008,37 @@ msgid "" "Frontend>` know that :ref:`setuptools` is the :term:`build backend ` for this project." msgstr "" +"Este é o método padronizado para permitir que :term:`frontends de construção " +"` saibam que :ref:`setuptools` é o :term:`backend de " +"construção ` para este projeto." #: ../source/guides/modernize-setup-py-project.rst:63 msgid "" "Note that the presence of a :file:`pyproject.toml` file (even if empty) " "triggers :ref:`pip` to change its default behavior to use *build isolation*." msgstr "" +"Observe que a presença de um arquivo :file:`pyproject.toml` (mesmo que " +"vazio) aciona :ref:`pip` para alterar seu comportamento padrão para usar " +"*isolamento de construção*." #: ../source/guides/modernize-setup-py-project.rst:68 -#, fuzzy -#| msgid "Linux distribution packages" msgid ":ref:`distributing-packages`" -msgstr "Pacotes de distribuição Linux" +msgstr ":ref:`distributing-packages`" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -#, fuzzy -#| msgid "Declaring build system dependencies" -msgid ":ref:`declaring-build-dependencies`" -msgstr "Declarando dependências do sistema de construção" +msgid ":ref:`pyproject-build-system-table`" +msgstr ":ref:`pyproject-build-system-table`" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" -msgstr "" +msgstr ":doc:`pip:reference/build-system/pyproject-toml`" #: ../source/guides/modernize-setup-py-project.rst:74 msgid "How to handle additional build-time dependencies?" -msgstr "" +msgstr "Como lidar com dependências de tempo de construção adicionais?" #: ../source/guides/modernize-setup-py-project.rst:76 msgid "" @@ -7351,22 +7048,29 @@ msgid "" "frontend knows to install them when building the :term:`distributions " "`." msgstr "" +"Além do próprio setuptools, se :file:`setup.py` depende de outras " +"bibliotecas de terceiros (fora da biblioteca padrão do Python), elas devem " +"ser listadas na lista ``requires`` do ``[build-system ]`` tabela, para que o " +"frontend de construção saiba instalá-los ao construir as :term:" +"`distribuições `." #: ../source/guides/modernize-setup-py-project.rst:82 #: ../source/guides/modernize-setup-py-project.rst:139 #: ../source/guides/modernize-setup-py-project.rst:174 msgid "For example, a :file:`setup.py` file such as this:" -msgstr "" +msgstr "Por exemplo, um arquivo :file:`setup.py` como este:" #: ../source/guides/modernize-setup-py-project.rst:99 msgid "" "requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " "unchanged):" msgstr "" +"requer um arquivo :file:`pyproject.toml` como este (:file:`setup.py` " +"permanece inalterado):" #: ../source/guides/modernize-setup-py-project.rst:117 msgid "What is the build isolation feature?" -msgstr "" +msgstr "Qual é o recurso de isolamento de compilação?" #: ../source/guides/modernize-setup-py-project.rst:119 msgid "" @@ -7374,76 +7078,84 @@ msgid "" "install only the build dependencies (and their dependencies) that are listed " "under ``build-system.requires`` and trigger the build in that environment." msgstr "" +"Frontends de construção normalmente criam um ambiente virtual efêmero onde " +"instalam apenas as dependências de construção (e suas dependências) listadas " +"em ``build-system.requires`` e acionam a construção nesse ambiente." #: ../source/guides/modernize-setup-py-project.rst:124 msgid "" "For some projects this isolation is unwanted and it can be deactivated as " "follows:" msgstr "" +"Para alguns projetos este isolamento é indesejado e pode ser desativado da " +"seguinte forma:" #: ../source/guides/modernize-setup-py-project.rst:126 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m build --no-isolation``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python -m build --no-isolation``" #: ../source/guides/modernize-setup-py-project.rst:127 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m install --no-build-isolation``" -msgstr "Sim (``python -m pip uninstall``)" +msgstr "``python -m install --no-build-isolation``" #: ../source/guides/modernize-setup-py-project.rst:135 -#, fuzzy -#| msgid "Using package metadata" msgid "How to handle packaging metadata?" -msgstr "Usando metadados de pacote" +msgstr "Como lidar com metadados de empacotamento?" #: ../source/guides/modernize-setup-py-project.rst:137 msgid "" "All static metadata can optionally be moved to a ``[project]`` table in :" "file:`pyproject.toml`." msgstr "" +"Todos os metadados estáticos podem opcionalmente ser movidos para uma tabela " +"``[project]`` em :file:`pyproject.toml`." #: ../source/guides/modernize-setup-py-project.rst:151 msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" msgstr "" +"pode ser totalmente substituído por um arquivo :file:`pyproject.toml` como " +"este:" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" +"Leia :ref:`pyproject-project-table` para a especificação completa do " +"conteúdo permitido na tabela ``[project]``." #: ../source/guides/modernize-setup-py-project.rst:169 msgid "How to handle dynamic metadata?" -msgstr "" +msgstr "Como lidar com metadados dinâmicos?" #: ../source/guides/modernize-setup-py-project.rst:171 msgid "" "If some packaging metadata fields are not static they need to be listed as " "``dynamic`` in this ``[project]`` table." msgstr "" +"Se alguns campos de metadados de empacotamento não forem estáticos, eles " +"precisam ser listados como ``dynamic`` nesta tabela ``[project]``." #: ../source/guides/modernize-setup-py-project.rst:191 msgid "can be modernized as follows:" -msgstr "" +msgstr "pode ser modernizado desta forma:" #: ../source/guides/modernize-setup-py-project.rst:223 -#, fuzzy -#| msgid "Declaring project metadata" msgid ":ref:`declaring-project-metadata-dynamic`" -msgstr "Declarando os metadados do projeto" +msgstr ":ref:`declaring-project-metadata-dynamic`" #: ../source/guides/modernize-setup-py-project.rst:227 msgid "What if something that can not be changed expects a ``setup.py`` file?" msgstr "" +"E se alguma coisa que não possa ser alterar esperar um arquivo ``setup.py``?" #: ../source/guides/modernize-setup-py-project.rst:229 msgid "" "For example, a process exists that can not be changed easily and it needs to " "execute a command such as ``python setup.py --name``." msgstr "" +"Por exemplo, existe um processo que não pode ser alterado facilmente e " +"precisa executar um comando como ``python setup.py --name``." #: ../source/guides/modernize-setup-py-project.rst:232 msgid "" @@ -7451,16 +7163,17 @@ msgid "" "tree even after all its content has been moved to :file:`pyproject.toml`. " "This file can be as minimalistic as this:" msgstr "" +"É perfeitamente normal deixar um arquivo :file:`setup.py` na árvore de " +"fontes do projeto mesmo depois de todo o seu conteúdo ter sido movido para :" +"file:`pyproject.toml`. Este arquivo pode ser tão minimalista quanto este:" -#: ../source/guides/modernize-setup-py-project.rst:247 -#, fuzzy -#| msgid "Declaring project metadata" -msgid ":ref:`declaring-project-metadata`" -msgstr "Declarando os metadados do projeto" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" -msgstr "" +msgstr ":doc:`setuptools:build_meta`" #: ../source/guides/multi-version-installs.rst:6 msgid "Multi-version installs" @@ -8036,22 +7749,16 @@ msgstr "" "no C `." #: ../source/guides/packaging-binary-extensions.rst:231 -#, fuzzy -#| msgid "" -#| "mention again that all this is one of the reasons why you probably " -#| "*don't* want to handcode your extension modules :)" msgid "" "FIXME: Elaborate that all this is one of the reasons why you probably " "*don't* want to handcode your extension modules :)" msgstr "" -"mencionar novamente que tudo isso é uma das razões pelas quais você " +"CORRIGIR: Elaborar que tudo isso é uma das razões pelas quais você " "provavelmente *não* deseja codificar manualmente seus módulos de extensão :)" #: ../source/guides/packaging-binary-extensions.rst:236 -#, fuzzy -#| msgid "mention the module lifecycle" msgid "Extension module lifecycle" -msgstr "mencionar o ciclo de vida dos módulos" +msgstr "Ciclo de vida dos módulos de extensão" #: ../source/guides/packaging-binary-extensions.rst:238 #: ../source/guides/packaging-binary-extensions.rst:244 @@ -8059,28 +7766,23 @@ msgstr "mencionar o ciclo de vida dos módulos" #: ../source/guides/packaging-binary-extensions.rst:256 #: ../source/guides/packaging-binary-extensions.rst:376 msgid "FIXME: This section needs to be fleshed out." -msgstr "" +msgstr "CORRIGIR: Esta seção precisa ser mais detalhada." #: ../source/guides/packaging-binary-extensions.rst:242 -#, fuzzy -#| msgid "mention the challenges of shared static state and subinterpreters" msgid "Implications of shared static state and subinterpreters" -msgstr "" -"mencionar os desafios do estado estático compartilhado e subinterpretadores" +msgstr "Implicações do estado estático compartilhado e subinterpretadores" #: ../source/guides/packaging-binary-extensions.rst:248 msgid "Implications of the GIL" -msgstr "" +msgstr "Implicações do GIL" #: ../source/guides/packaging-binary-extensions.rst:254 -#, fuzzy -#| msgid "mention the memory allocation APIs in 3.4+" msgid "Memory allocation APIs" -msgstr "mencionar as APIs de alocação de memória em 3.4+" +msgstr "APIs de alocação de memória" #: ../source/guides/packaging-binary-extensions.rst:262 msgid "ABI Compatibility" -msgstr "" +msgstr "Compatibilidade da ABI" #: ../source/guides/packaging-binary-extensions.rst:264 msgid "" @@ -8089,6 +7791,11 @@ msgid "" "module against one version of Python, it is only guaranteed to work with the " "same minor version of Python and not with any other minor versions." msgstr "" +"A API C do CPython não garante a estabilidade da ABI entre versões " +"secundárias (3.2, 3.3, 3.4, etc.). Isso significa que, normalmente, se você " +"construir um módulo de extensão em uma versão do Python, é garantido que ele " +"funcionará apenas com a mesma versão secundária do Python e não com " +"quaisquer outras versões secundárias." #: ../source/guides/packaging-binary-extensions.rst:270 msgid "" @@ -8098,6 +7805,12 @@ msgid "" "Wheels containing extensions built against the stable ABI use the ``abi3`` " "ABI tag, to reflect that they're compatible with all Python 3.x versions." msgstr "" +"Python 3.2 introduziu a API Limitada (\"Limited API\"), que é um subconjunto " +"bem definido da API C do Python. Os símbolos necessários para a API Limitada " +"formam a \"ABI estável\", que é garantidamente compatível com todas as " +"versões do Python 3.x. Wheels contendo extensões construídas na ABI estável " +"usam a tag de ABI ``abi3``, para refletir que são compatíveis com todas as " +"versões do Python 3.x." #: ../source/guides/packaging-binary-extensions.rst:277 msgid "" @@ -8105,6 +7818,9 @@ msgid "" "information about the API / ABI stability guarantees, how to use the Limited " "API and the exact contents of the \"Limited API\"." msgstr "" +"A página :doc:`Estabilidade da API C ` do CPython " +"fornece informações detalhadas sobre as garantias de estabilidade da API/" +"ABI, como usar a API Limitada e o conteúdo exato da \"API Limitada\"." #: ../source/guides/packaging-binary-extensions.rst:283 msgid "Building binary extensions" @@ -8113,21 +7829,14 @@ msgstr "Construindo extensões binárias" #: ../source/guides/packaging-binary-extensions.rst:285 msgid "FIXME: Cover the build-backends available for building extensions." msgstr "" +"CORRIGIR: Cobrir os backends de construção disponíveis para construir " +"extensões." #: ../source/guides/packaging-binary-extensions.rst:288 msgid "Building extensions for multiple platforms" msgstr "Construindo extensões para várias plataformas" #: ../source/guides/packaging-binary-extensions.rst:290 -#, fuzzy -#| msgid "" -#| "If you plan to distribute your extension, you should provide :term:" -#| "`wheels ` for all the platforms you intend to support. For most " -#| "extensions, this is at least one package per Python version times the " -#| "number of OS and architectures you support. These are usually built on " -#| "continuous integration (CI) systems. There are tools to help you build " -#| "highly redistributable binaries from CI; these include :ref:" -#| "`cibuildwheel` and :ref:`multibuild`." msgid "" "If you plan to distribute your extension, you should provide :term:`wheels " "` for all the platforms you intend to support. These are usually " @@ -8136,12 +7845,10 @@ msgid "" "`cibuildwheel` and :ref:`multibuild`." msgstr "" "Se você planeja distribuir sua extensão, você deve fornecer :term:`wheels " -"` para todas as plataformas que pretende oferecer suporte. Para a " -"maioria das extensões, é pelo menos um pacote por versão Python vezes o " -"número de sistemas opcionais e arquiteturas aos quais você oferece suporte. " -"Geralmente são construídos em sistemas de integração contínua (CI). Existem " -"ferramentas para lhe ajudar a construir binários altamente redistribuíveis " -"de CI; estes incluem :ref:`cibuildwheel` e :ref:`multibuild`." +"` para todas as plataformas que pretende oferecer suporte. Geralmente " +"são construídos em sistemas de integração contínua (CI). Existem ferramentas " +"para lhe ajudar a construir binários altamente redistribuíveis de CI; estes " +"incluem :ref:`cibuildwheel` e :ref:`multibuild`." #: ../source/guides/packaging-binary-extensions.rst:296 msgid "" @@ -8149,6 +7856,9 @@ msgid "" "intend to support. This means that the number of wheels you need to build is " "the product of::" msgstr "" +"Para a maioria das extensões, você precisará construir wheels para todas as " +"plataformas que pretende suportar. Isso significa que o número de wheels que " +"você precisa construir é o produto de::" #: ../source/guides/packaging-binary-extensions.rst:302 msgid "" @@ -8158,6 +7868,11 @@ msgid "" "eliminating one dimension of the matrix. It also removes the need to " "generate new wheels for each new minor version of Python." msgstr "" +"Usar a :ref:`ABI Estável ` do CPython pode ajudar a " +"reduzir significativamente o número de wheels que você precisa fornecer, já " +"que um único wheel em uma plataforma pode ser usada com todas as versões " +"secundárias do Python; eliminando uma dimensão da matriz. Também elimina a " +"necessidade de gerar novos wheels para cada nova versão secundária do Python." #: ../source/guides/packaging-binary-extensions.rst:309 msgid "Binary extensions for Windows" @@ -8269,10 +7984,14 @@ msgid "" "using the build-backend and upload it to PyPI using :doc:`twine `." msgstr "" +"A publicação de extensões binárias por meio do PyPI usa os mesmos mecanismos " +"de upload que a publicação de pacotes Python puros. Você constrói um arquivo " +"wheel para sua extensão usando o backend de construção e carrega-o no PyPI " +"usando :doc:`twine `." #: ../source/guides/packaging-binary-extensions.rst:365 msgid "Avoid binary-only releases" -msgstr "" +msgstr "Evite lançamentos somente binários" #: ../source/guides/packaging-binary-extensions.rst:367 msgid "" @@ -8282,12 +8001,16 @@ msgid "" "certain Linux distributions that build from source within their own build " "systems for the distro package repositories." msgstr "" +"É altamente recomendável que você publique suas extensões binárias, bem como " +"o código-fonte usado para construí-las. Isso permite que os usuários criem a " +"extensão a partir do código-fonte, se necessário. Notavelmente, isso é " +"necessário para certas distribuições Linux que compilam a partir do código-" +"fonte em seus próprios sistemas de compilação para os repositórios de " +"pacotes de distribuição." #: ../source/guides/packaging-binary-extensions.rst:374 -#, fuzzy -#| msgid "cover weak linking" msgid "Weak linking" -msgstr "cobrir ligação fraca" +msgstr "Ligação fraca" #: ../source/guides/packaging-binary-extensions.rst:379 msgid "Additional resources" @@ -8362,11 +8085,11 @@ msgstr "" "`Escrevendo módulos de extensão cpython usando C++ `_" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "Empacotando pacotes de espaço de nomes" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -8380,21 +8103,21 @@ msgstr "" "**distribuições** em este documento para evitar ambiguidade). Por exemplo, " "se você tiver a seguinte estrutura de pacote:" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "E você usa este pacote em seu código assim::" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" "Então você pode quebrar esses subpacotes em duas distribuições separadas:" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" "Cada subpacote pode agora ser instalado, usado e versionado separadamente." -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -8413,23 +8136,19 @@ msgstr "" "``import mynamespace_subpackage_a as subpackage_a`` para manter o objeto de " "importação curto)." -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "Criando um pacote de espaço de nomes" -#: ../source/guides/packaging-namespace-packages.rst:62 -#, fuzzy -#| msgid "" -#| "There are currently three different approaches to creating namespace " -#| "packages:" +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -"Atualmente, existem três abordagens diferentes para a criação de pacotes de " -"espaço de nomes:" +"Atualmente, existem duas abordagens diferentes para a criação de pacotes de " +"espaço de nomes, das quais a última é desencorajado:" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -8441,23 +8160,20 @@ msgstr "" "Isso é recomendado se os pacotes em seu espaço de nomes precisarem apenas " "oferecer suporte ao Python 3 e à instalação via ``pip``." -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" +"Use `pacotes de espaço de nomes legados`_. Isso compreende `pacotes de " +"espaço de nomes no estilo pkgutil`_ e `pacotes de espaço de nomes no estilo " +"pkg_resources`_." -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "Pacotes se espaço de nomes nativos" -#: ../source/guides/packaging-namespace-packages.rst:75 -#, fuzzy -#| msgid "" -#| "Python 3.3 added **implicit** namespace packages from :pep:`420`. All " -#| "that is required to create a native namespace package is that you just " -#| "omit :file:`__init__.py` from the namespace package directory. An example " -#| "file structure:" +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -8467,9 +8183,10 @@ msgstr "" "Python 3.3 adicionou pacotes de espaço de nomes **implícitos** a partir da :" "pep:`420`. Tudo o que é necessário para criar um pacote de espaço de nomes " "nativo é omitir :file:`__init__.py` do diretório do pacote de espaço de " -"nomes. Um exemplo de estrutura de arquivo:" +"nomes. Um exemplo de estrutura de arquivo (seguindo :ref:`src-layout " +"`):" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -8481,7 +8198,7 @@ msgstr "" "pkgutil. Se alguma distribuição não o fizer, isso fará com que a lógica do " "espaço de nomes falhe e os outros subpacotes não serão importáveis." -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -8489,24 +8206,29 @@ msgid "" "exclusions or inclusions of packages yourself, this is possible to be " "configured in the top-level :file:`pyproject.toml`:" msgstr "" +"A estrutura de diretórios ``src-layout`` permite a descoberta automática de " +"pacotes pela maioria dos :term:`backends de construção `. " +"Veja :ref:`src-layout-vs-flat-layout` para mais informações. Se, no entanto, " +"você mesmo deseja gerenciar exclusões ou inclusões de pacotes, isso é " +"possível de ser configurado no :file:`pyproject.toml` de nível superior:" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" -msgstr "" +msgstr "O mesmo pode ser feito com um :file:`setup.cfg`:" -#: ../source/guides/packaging-namespace-packages.rst:127 -#, fuzzy -#| msgid ":file:`setup.cfg`" +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" -msgstr ":file:`setup.cfg`" +msgstr "Ou :file:`setup.py`:" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" +":ref:`setuptools` irá pesquisar na estrutura de diretórios por pacotes de " +"espaço de nomes implícitos por padrão." -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." @@ -8515,7 +8237,7 @@ msgstr "" "pode ser encontrado no `projeto exemplo de pacote de espaço de nomes " "nativo`_." -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -8528,27 +8250,32 @@ msgstr "" "de nomes no estilo pkgutil nas distribuições que precisam oferecer suporte a " "Python 2 e 3." -#: ../source/guides/packaging-namespace-packages.rst:156 -#, fuzzy -#| msgid "Using namespace packages" +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" -msgstr "Usando pacotes de espaço de nomes" +msgstr "Pacotes de espaço de nomes legados" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " "need compatibility with packages already using this method. Also, :doc:" "`pkg_resources ` has been deprecated." msgstr "" +"Esses dois métodos, que eram usados para criar pacotes de espaço de nomes " +"antes de :pep:`420`, agora são considerados descontinuados e não devem ser " +"usados a menos que você precise de compatibilidade com pacotes que já usam " +"esse método. Além disso, :doc:`pkg_resources ` foi " +"descontinuado." -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" +"Para migrar um pacote existente, todos os pacotes que compartilham o espaço " +"de nomes devem ser migrados simultaneamente." -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -8561,11 +8288,11 @@ msgstr "" "aconselhável usar métodos diferentes em distribuições diferentes que " "fornecem pacotes para o mesmo espaço de nomes." -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "Pacotes de espaço de nomes no estilo pkgutil" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -8579,7 +8306,7 @@ msgstr "" "2.3+ e Python 3. Esta é a abordagem recomendada para o nível mais alto de " "compatibilidade." -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" @@ -8587,28 +8314,17 @@ msgstr "" "Para criar um pacote de espaço de nomes no estilo pkgutil, você precisa " "fornecer um arquivo :file:`__init__.py` para o pacote de espaço de nomes:" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 -#, fuzzy -#| msgid "" -#| "The :file:`__init__.py` file for the namespace package needs to contain " -#| "**only** the following:" +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" "O arquivo :file:`__init__.py` para o pacote de espaço de nomes precisa " -"conter **apenas** o seguinte:" +"conter o seguinte:" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 -#, fuzzy -#| msgid "" -#| "**Every** distribution that uses the namespace package must include an " -#| "identical :file:`__init__.py`. If any distribution does not, it will " -#| "cause the namespace logic to fail and the other sub-packages will not be " -#| "importable. Any additional code in :file:`__init__.py` will be " -#| "inaccessible." +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -8616,12 +8332,12 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" "**Cada** distribuição que usa o pacote de espaço de nomes deve incluir um :" -"file:`__init__.py` idêntico. Se alguma distribuição não o fizer, isso fará " -"com que a lógica do espaço de nomes falhe e os outros subpacotes não serão " +"file:`__init__.py`. Se alguma distribuição não o fizer, isso fará com que a " +"lógica do espaço de nomes falhe e os outros subpacotes não serão " "importáveis. Qualquer código adicional no :file:`__init__.py` ficará " "inacessível." -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." @@ -8630,11 +8346,11 @@ msgstr "" "estilo pkgutil pode ser encontrado no `projeto exemplo de espaço de nomes de " "pkgutil`_." -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "Pacotes de espaço de nomes no estilo pkg_resources" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -8655,7 +8371,7 @@ msgstr "" "os diferentes métodos não são compatíveis entre si e não é aconselhável " "tentar migrar um pacote existente." -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" @@ -8664,7 +8380,7 @@ msgstr "" "precisa fornecer um arquivo :file:`__init __. Py` para o pacote de espaço de " "nomes:" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" @@ -8672,7 +8388,7 @@ msgstr "" "Algumas recomendações mais antigas aconselham o seguinte no :file:`__init__." "py` de pacotes de espaço de nomes:" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -8687,7 +8403,7 @@ msgstr "" "uma preocupação, então o pacote deve depender explicitamente de setuptools " "via ``install_requires``." -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" @@ -8696,7 +8412,7 @@ msgstr "" "``namespace_packages`` para :func:`~setuptools.setup` no :file:`setup.py`. " "Por exemplo:" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -8713,13 +8429,6 @@ msgstr "" "CI/CD do GitHub Actions" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 -#, fuzzy -#| msgid "" -#| "`GitHub Actions CI/CD`_ allows you to run a series of commands whenever " -#| "an event occurs on the GitHub platform. One popular choice is having a " -#| "workflow that's triggered by a ``push`` event. This guide shows you how " -#| "to publish a Python distribution whenever a tagged commit is pushed. It " -#| "will use the `pypa/gh-action-pypi-publish GitHub Action`_." msgid "" "`GitHub Actions CI/CD`_ allows you to run a series of commands whenever an " "event occurs on the GitHub platform. One popular choice is having a workflow " @@ -8733,7 +8442,10 @@ msgstr "" "sempre que ocorrer um evento na plataforma GitHub. Uma escolha popular é ter " "um fluxo de trabalho que é disparado por um evento ``push``. Este guia " "mostra como publicar uma distribuição Python sempre que um commit marcado é " -"enviado. Ele usará o `GitHub Action pypa/gh-action-pypi-publish`_." +"enviado. Ele usará o `GitHub Action pypa/gh-action-pypi-publish`_ para " +"publicação. Ele também usa as actions `upload-artifact`_ e `download-" +"artifact`_ do GitHub para temporariamente armazenar e baixar os pacotes " +"fontes." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:17 msgid "" @@ -8750,7 +8462,7 @@ msgstr "" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:23 msgid "Configuring trusted publishing" -msgstr "" +msgstr "Configurando publicação confiável" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 msgid "" @@ -8762,6 +8474,13 @@ msgid "" "doc:`devpi `, you may need to provide a username/password " "combination." msgstr "" +"Este guia se baseia na implementação de `publicação confiável`_ do PyPI para " +"se conectar ao `CI/CD do GitHub Actions`_. Isso é recomendado por motivos de " +"segurança, pois os tokens gerados são criados para cada um dos seus projetos " +"individualmente e expiram automaticamente. Caso contrário, você precisará " +"gerar um `token de API`_ para PyPI e TestPyPI. No caso de publicação em " +"índices de terceiros como :doc:`devpi `, pode ser necessário " +"fornecer uma combinação de nome de usuário/senha." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:33 msgid "" @@ -8771,6 +8490,11 @@ msgid "" "`. However it is also possible to add `trusted publishing`_ to any " "pre-existing project, if you are its owner." msgstr "" +"Como este guia demonstrará o envio para PyPI e TestPyPI, precisaremos de " +"dois publicadores confiáveis configurados. As etapas a seguir guiarão você " +"na criação dos publicadores \"pendentes\" para seu novo :term:`Projeto PyPI " +"`. No entanto, também é possível adicionar `publicação confiável`_ " +"a qualquer projeto preexistente, se você for o proprietário." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:42 msgid "" @@ -8780,6 +8504,11 @@ msgid "" "repository and revoke them in your PyPI and TestPyPI account settings in " "case you are replacing your old setup with the new one." msgstr "" +"Se você seguiu versões anteriores deste guia, você criou os segredos " +"``PYPI_API_TOKEN`` e ``TEST_PYPI_API_TOKEN`` para acesso direto ao PyPI e " +"TestPyPI. Eles estão descontinuados agora e você deve removê-los de seu " +"repositório GitHub e revogá-los nas configurações de sua conta PyPI e " +"TestPyPI, caso esteja substituindo sua configuração antiga pela nova." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:49 msgid "Let's begin! 🚀" @@ -8787,7 +8516,7 @@ msgstr "Vamos começar! 🚀" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:51 msgid "Go to https://pypi.org/manage/account/publishing/." -msgstr "" +msgstr "Acesse https://pypi.org/manage/account/publishing/." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:52 msgid "" @@ -8799,25 +8528,32 @@ msgid "" "(``pypi``) we're going set up under your repository. Register the trusted " "publisher." msgstr "" +"Preencha o nome com o qual deseja publicar seu novo :term:`projeto PyPI " +"` em (o valor ``name`` em seu ``setup.cfg`` ou ``pyproject.toml``), " +"o nome do proprietário do repositório no GitHub (organização ou usuário), e " +"nome do repositório, e o nome do arquivo de fluxo de trabalho de lançamento " +"na pasta ``.github/``, consulte :ref:`workflow-definition`. Por fim, " +"adicione o nome do ambiente do GitHub (``pypi``) que iremos configurar em " +"seu repositório. Registre o publicador confiável." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:61 -#, fuzzy -#| msgid "" -#| "Now, go to https://test.pypi.org/manage/account/#api-tokens and repeat " -#| "the steps. Save that TestPyPI token on GitHub as ``TEST_PYPI_API_TOKEN``." msgid "" "Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " "second step, but this time, enter ``testpypi`` as the name of the GitHub " "Environment." msgstr "" -"Agora, vá para https://test.pypi.org/manage/account/#api-tokens e repita as " -"etapas. Salve esse token de TestePyPI no GitHub como ``TEST_PYPI_API_TOKEN``." +"Agora, acesse https://test.pypi.org/manage/account/publishing/ e repita a " +"segunda etapa, mas desta vez, insira ``testpypi`` como o nome do ambiente do " +"GitHub." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:64 msgid "" "Your \"pending\" publishers are now ready for their first use and will " "create your projects automatically once you use them for the first time." msgstr "" +"Seus publicadores \"pendentes\" agora estão prontos para o primeiro uso e " +"criarão seus projetos automaticamente assim que você usá-los pela primeira " +"vez." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:70 msgid "" @@ -8834,6 +8570,10 @@ msgid "" "environments-for-deployment#deployment-protection-rules>`_ on each run for " "the ``pypi`` environment." msgstr "" +"Por motivos de segurança, você deve exigir a `aprovação manual `_ em cada execução " +"para o ambiente ``pypi``." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:83 msgid "Creating a workflow definition" @@ -8870,12 +8610,17 @@ msgid "" "We will have to define two jobs to publish to PyPI and TestPyPI " "respectively, and an additional job to build the distribution packages." msgstr "" +"Teremos que definir dois trabalhos (\"jobs\") para publicar em PyPI e " +"TestPyPI respectivamente, e um trabalho adicional para construir os pacotes " +"de distribuição." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:105 msgid "" "First, we'll define the job for building the dist packages of your project " "and storing them for later use:" msgstr "" +"Primeiro, definiremos o trabalho para construir os pacotes dist do seu " +"projeto e armazená-los para uso posterior:" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:113 msgid "" @@ -8886,16 +8631,12 @@ msgstr "" "instalará e ativará o lançamento mais recente disponível do Python 3." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:116 -#, fuzzy -#| msgid "" -#| "And now we can build dists from source. In this example, we'll use " -#| "``build`` package." msgid "" "And now we can build the dists from source and store them. In this example, " "we'll use the ``build`` package. So add this to the steps list:" msgstr "" -"E agora podemos construir dists a partir da fonte. Neste exemplo, usaremos o " -"pacote ``build``." +"E agora podemos construir os dists a partir da fonte e armazená-los. Neste " +"exemplo, usaremos o pacote ``build``. Então, adicione isso à lista de etapas:" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:126 msgid "Defining a workflow job environment" @@ -8911,46 +8652,46 @@ msgid "" "acquiring an OpenID Connect token that the ``pypi-publish`` actions needs to " "implement secretless trusted publishing to PyPI." msgstr "" +"Agora, vamos adicionar a configuração inicial para nosso trabalho que será " +"publicado no PyPI. É um processo que executará comandos que definiremos mais " +"tarde. Neste guia, usaremos a versão estável mais recente do Ubuntu LTS " +"fornecida pelo GitHub Actions. Isso também define um ambiente GitHub para o " +"trabalho ser executado em seu contexto e uma URL a ser exibida na interface " +"do GitHub. Além disso, permite adquirir um token OpenID Connect que as ações " +"``pypi-publish`` precisam para implementar publicação confiável sem segredo " +"para PyPI." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:142 msgid "" "This will also ensure that the PyPI publishing workflow is only triggered if " "the current commit is tagged." msgstr "" +"Isso também garantirá que o fluxo de trabalho de publicação do PyPI só seja " +"acionado se o commit atual estiver marcado." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:146 -#, fuzzy -#| msgid "Publishing the distribution to PyPI and TestPyPI" msgid "Publishing the distribution to PyPI" -msgstr "Publicando a distribuição para PyPI e TestPyPI" +msgstr "Publicando a distribuição para PyPI" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 msgid "Finally, add the following steps at the end:" msgstr "Finalmente, adicione as seguintes etapas ao final:" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:155 -#, fuzzy -#| msgid "" -#| "These two steps use the `pypa/gh-action-pypi-publish`_ GitHub Action: the " -#| "first one uploads contents of the ``dist/`` folder into TestPyPI " -#| "unconditionally and the second does that to PyPI, but only if the current " -#| "commit is tagged." msgid "" "This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " "stored distribution package has been downloaded by the `download-artifact`_ " "action, it uploads the contents of the ``dist/`` folder into PyPI " "unconditionally." msgstr "" -"Essas duas etapas usam a GitHub Action `pypa/gh-action-pypi-publish`_: a " -"primeira carrega o conteúdo da pasta ``dist /`` para TestPyPI " -"incondicionalmente e a segunda faz isso para PyPI, mas apenas se o commit " -"atual estiver marcado." +"Essa etapa usa a GitHub Action `pypa/gh-action-pypi-publish`_: após o " +"primeiro pacote de distribuição armazenado ter sido baixado pela ação " +"`download-artifact`_, ele envia o conteúdo da pasta ``dist /`` para PyPI " +"incondicionalmente." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:161 -#, fuzzy -#| msgid "Linux distribution packages" msgid "Signing the distribution packages" -msgstr "Pacotes de distribuição Linux" +msgstr "Assinando os pacotes de distribuição" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:163 msgid "" @@ -8958,6 +8699,9 @@ msgid "" "artifact signing system `used to sign CPython `_." msgstr "" +"O trabalho a seguir assina os pacotes de distribuição com `Sigstore`_, o " +"mesmo sistema de assinatura de artefato `usado para assinar o CPython " +"`_." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:166 msgid "" @@ -8967,10 +8711,17 @@ msgid "" "further customised. See the `gh release documentation `_ as a reference." msgstr "" +"Em primeiro lugar, ele usa `sigstore/gh-action-sigstore-python do GitHub " +"Action`_ para assinar os pacotes de distribuição. Na próxima etapa, uma " +"versão vazia do GitHub da tag atual é criada usando a CLI ``gh``. Observe " +"que esta etapa pode ser ainda mais personalizada. Consulte a `documentação " +"de lançamento do gh `_ como " +"referência." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 msgid "Finally, the signed distributions are uploaded to the GitHub Release." msgstr "" +"Finalmente, as distribuições assinadas são enviadas para o GitHub Release." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:182 msgid "" @@ -8978,16 +8729,22 @@ msgid "" "`removed from PyPI `_. " "However, this job is not mandatory for uploading to PyPI and can be omitted." msgstr "" +"Este é um substituto para assinaturas GPG, para as quais o suporte foi " +"`removido do PyPI `_. " +"No entanto, este trabalho não é obrigatório para o envio para PyPI e pode " +"ser omitido." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 msgid "Separate workflow for publishing to TestPyPI" -msgstr "" +msgstr "Fluxo de trabalho separado para publicação no TestPyPI" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 msgid "" "Now, repeat these steps and create another job for publishing to the " "TestPyPI package index under the ``jobs`` section:" msgstr "" +"Agora, repita essas etapas e crie outro trabalho para publicação no índice " +"do pacote TestPyPI na seção ``jobs``:" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 msgid "" @@ -8995,15 +8752,20 @@ msgid "" "typically unnecessary as it's designed to run on each commit to the main " "branch and is often used to indicate a healthy release publishing pipeline." msgstr "" +"Exigir aprovações manuais no ambiente GitHub ``testpypi`` normalmente é " +"desnecessário, pois ele é projetado para ser executado em cada commit no " +"branch principal e é frequentemente usado para indicar um pipeline de " +"publicação de lançamento íntegro." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:204 msgid "The whole CI/CD workflow" -msgstr "" +msgstr "O fluxo de trabalho de CI/CD completo" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:206 msgid "" "This paragraph showcases the whole workflow after following the above guide." msgstr "" +"Este parágrafo mostra todo o fluxo de trabalho após seguir o guia acima." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:214 msgid "That's all, folks!" @@ -9030,34 +8792,46 @@ msgid "" "increased, but a better solution may constitute to use a PyPI-compatible " "server like :ref:`pypiserver` in the CI for testing purposes." msgstr "" +"Se o seu repositório tiver atividade de commit frequente e cada push for " +"carregado no TestPyPI conforme descrito, o projeto poderá exceder o `limite " +"de tamanho do projeto PyPI `_. O " +"limite poderia ser aumentado, mas uma solução melhor pode consistir em usar " +"um servidor compatível com PyPI como :ref:`pypiserver` no CI para fins de " +"teste." #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:232 msgid "" "It is recommended to keep the integrated GitHub Actions at their latest " "versions, updating them frequently." msgstr "" +"Recomenda-se manter o GitHub Actions integrado em suas versões mais " +"recentes, atualizando-as frequentemente." #: ../source/guides/section-build-and-publish.rst:3 -#, fuzzy -#| msgid "Building and Publishing Projects:" msgid "Building and Publishing" -msgstr "Construindo e publicando projetos:" +msgstr "Construção e publicação" #: ../source/guides/section-hosting.rst:3 msgid "Hosting" -msgstr "" +msgstr "Hospedagem" #: ../source/guides/section-install.rst:3 -#, fuzzy -#| msgid "Installation format" msgid "Installation" -msgstr "Formato de instalação" +msgstr "Instalação" #: ../source/guides/single-sourcing-package-version.rst:5 msgid "Single-sourcing the package version" msgstr "Mantendo uma única fonte da versão do pacote" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" @@ -9065,7 +8839,7 @@ msgstr "" "Existem muitas técnicas para manter uma única fonte para o número de versão " "do seu projeto:" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" @@ -9073,7 +8847,7 @@ msgstr "" "Leia o arquivo em :file:`setup.py` e obtenha a versão. Exemplo (de `pip " "setup.py `_)::" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " @@ -9083,7 +8857,7 @@ msgstr "" "colocando o seguinte no arquivo :file:`setup.cfg` do projeto (substituindo " "\"pacote\" pelo nome de importação do pacote):" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." @@ -9091,7 +8865,7 @@ msgstr "" "A partir do lançamento do setuptools 61.0.0, pode-se especificar a versão " "dinamicamente no arquivo :file:`pyproject.toml` do projeto." -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." @@ -9099,7 +8873,7 @@ msgstr "" "Esteja ciente de que os indicadores de configuração declarativos, incluindo " "a diretiva ``attr:``, não são suportados em parâmetros para :file:`setup.py`." -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." @@ -9107,7 +8881,7 @@ msgstr "" "Use uma ferramenta de construção externa que gerencia a atualização de ambos " "os locais ou oferece uma API que ambos os locais podem usar." -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -9120,7 +8894,7 @@ msgstr "" "`_, `zest.releaser `_." -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " @@ -9130,7 +8904,7 @@ msgstr "" "dedicado em seu projeto (por exemplo, :file:`version.py`), então faça com " "que :file:`setup.py` leia e execute (``exec``) o valor em uma variável." -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." @@ -9138,7 +8912,7 @@ msgstr "" "Exemplo usando esta técnica: `warehouse `_." -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." @@ -9146,7 +8920,7 @@ msgstr "" "Coloque o valor em um arquivo de texto simples ``VERSION`` e tenha ambos :" "file:`setup.py` e o código do projeto lidos." -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." @@ -9154,7 +8928,7 @@ msgstr "" "Uma vantagem dessa técnica é que ela não é específica do Python. Qualquer " "ferramenta pode ler a versão." -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " @@ -9164,7 +8938,7 @@ msgstr "" "está incluído em todas as suas distribuições de fonte e binárias (por " "exemplo, adicione ``include VERSION`` ao seu :file:`MANIFEST.in`)." -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -9178,7 +8952,7 @@ msgstr "" "versões anteriores como o projeto ``importlib-metadata``.) A versão de um " "projeto instalado pode ser obtida com a API da seguinte forma::" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " @@ -9188,7 +8962,7 @@ msgstr "" "nos metadados de instalação, o que não é necessariamente o código que está " "importado no momento." -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" @@ -9198,7 +8972,7 @@ msgstr "" "então seu valor ``install_requires`` precisa ser editado para instalar " "``importlib-metadata`` em versões pré-3.8 do Python como::" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" @@ -9206,7 +8980,7 @@ msgstr "" "’Uma alternativa mais antiga (e menos eficiente) ao ``importlib.metadata`` é " "a API ``pkg_resources`` fornecida pelo ``setuptools``::" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." @@ -9215,7 +8989,7 @@ msgstr "" "de execução, então ``setuptools`` deve ser adicionado à lista " "``install_requires`` do projeto." -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." @@ -9223,7 +8997,7 @@ msgstr "" "Exemplo usando esta técnica: `setuptools `_." -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." @@ -9231,7 +9005,7 @@ msgstr "" "Defina o valor para ``__version__`` em ``sample/__init__.py`` e importe " "``sample`` no :file:`setup.py`." -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " @@ -9242,7 +9016,7 @@ msgstr "" "muito provavelmente ainda não estarão instalados quando :file:`setup.py` for " "executado." -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -9288,12 +9062,6 @@ msgid "Automated testing and continuous integration" msgstr "Testes automatizados e integração contínua" #: ../source/guides/supporting-multiple-python-versions.rst:50 -#, fuzzy -#| msgid "" -#| "Several hosted services for automated testing are available. These " -#| "services will typically monitor your source code repository (e.g. at " -#| "`Github `_ or `Bitbucket `_) " -#| "and run your project's test suite every time a new commit is made." msgid "" "Several hosted services for automated testing are available. These services " "will typically monitor your source code repository (e.g. at `GitHub `_ ou `Bitbucket `_ ou `Bitbucket `_) e executar um conjunto de testes do seu projeto toda vez " "que um novo commit é feito." @@ -9495,13 +9263,6 @@ msgstr "" "no Windows não é trivial e pode exigir a compra de licenças de software." #: ../source/guides/supporting-windows-using-appveyor.rst:23 -#, fuzzy -#| msgid "" -#| "The Appveyor service is a continuous integration service, much like the " -#| "better-known `Travis`_ service that is commonly used for testing by " -#| "projects hosted on `Github`_. However, unlike Travis, the build workers " -#| "on Appveyor are Windows hosts and have the necessary compilers installed " -#| "to build Python extensions." msgid "" "The Appveyor service is a continuous integration service, much like the " "better-known `Travis`_ service that is commonly used for testing by projects " @@ -9511,7 +9272,7 @@ msgid "" msgstr "" "O serviço Appveyor é um serviço de integração contínua, muito parecido com o " "serviço `Travis`_ mais conhecido que é comumente usado para testes por " -"projetos hospedados no `Github`_. No entanto, ao contrário do Travis, os " +"projetos hospedados no `GitHub`_. No entanto, ao contrário do Travis, os " "workers de construção no Appveyor são hosts Windows e têm os compiladores " "necessários instalados para construir extensões Python." @@ -9549,17 +9310,12 @@ msgstr "" "código aberto." #: ../source/guides/supporting-windows-using-appveyor.rst:44 -#, fuzzy -#| msgid "" -#| "Appveyor provides integration with `Github`_ and `Bitbucket`_, so as long " -#| "as your project is hosted on one of those two services, setting up " -#| "Appveyor integration is straightforward." msgid "" "Appveyor provides integration with `GitHub`_ and `Bitbucket`_, so as long as " "your project is hosted on one of those two services, setting up Appveyor " "integration is straightforward." msgstr "" -"O Appveyor fornece integração com `Github`_ e `Bitbucket`_, portanto, desde " +"O Appveyor fornece integração com `GitHub`_ e `Bitbucket`_, portanto, desde " "que seu projeto esteja hospedado em um desses dois serviços, configurar a " "integração do Appveyor é simples." @@ -10191,16 +9947,6 @@ msgstr "" "consistência entre versões." #: ../source/guides/tool-recommendations.rst:96 -#, fuzzy -#| msgid "" -#| "Although you can use pure ``distutils`` for many projects, it does not " -#| "support defining dependencies on other projects and is missing several " -#| "convenience utilities for automatically populating distribution metadata " -#| "correctly that are provided by ``setuptools``. Being outside the standard " -#| "library, ``setuptools`` also offers a more consistent feature set across " -#| "different versions of Python, and (unlike ``distutils``), recent versions " -#| "of ``setuptools`` support all of the modern metadata fields described in :" -#| "ref:`core-metadata`." msgid "" "Although you can use pure :ref:`distutils` for many projects, it does not " "support defining dependencies on other projects and is missing several " @@ -10211,7 +9957,7 @@ msgid "" "``setuptools`` support all of the modern metadata fields described in :ref:" "`core-metadata`." msgstr "" -"Embora você possa usar ``distutils`` puro para muitos projetos, ele não " +"Embora você possa usar :ref:`distutils` puro para muitos projetos, ele não " "oferece suporta à definição de dependências em outros projetos e não possui " "vários utilitários de conveniência para preencher automaticamente os " "metadados de distribuição fornecidos pelo ``setuptools``. Estando fora da " @@ -10246,17 +9992,12 @@ msgstr "" "Incluindo arquivos em distribuições de código-fonte com ``MANIFEST.in``" #: ../source/guides/using-manifest-in.rst:7 -#, fuzzy -#| msgid "" -#| "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." msgid "" "The information on this page has moved to :doc:`setuptools:userguide/" "miscellaneous` in the setuptools documentation." msgstr "" -"Para mais informações, veja :doc:`Entry Points ` (pontos de entrada, em português) da :doc:`documentação do " -"setuptools `." +"As informações nesta página foram movidas para :doc:`setuptools:userguide/" +"miscellaneous` na documentação do setuptools." #: ../source/guides/using-testpypi.rst:7 msgid "" @@ -10343,18 +10084,20 @@ msgid "Setting up TestPyPI in :file:`.pypirc`" msgstr "Configurando TestPyPI no :file:`.pypirc`" #: ../source/guides/using-testpypi.rst:75 +#, fuzzy +#| msgid "" +#| "If you want to avoid entering your username, you can configure TestPyPI " +#| "in your :file:`$HOME/.pypirc`:" msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" "Se você quiser evitar de ter que inserir seu nome de usuário, pode " "configurar o TestPyPI em seu :file:`$HOME/.pypirc`:" #: ../source/guides/writing-pyproject-toml.rst:5 -#, fuzzy -#| msgid "Creating pyproject.toml" msgid "Writing your ``pyproject.toml``" -msgstr "Criando pyproject.toml" +msgstr "Escrevendo seu ``pyproject.toml``" #: ../source/guides/writing-pyproject-toml.rst:7 msgid "" @@ -10362,6 +10105,9 @@ msgid "" "as other tools such as linters, type checkers, etc. There are three possible " "TOML tables in this file." msgstr "" +"``pyproject.toml`` é um arquivo de configuração usado por ferramentas de " +"empacotamento, bem como outras ferramentas como linters, verificadores de " +"tipo, etc. Existem três tabelas TOML possíveis neste arquivo." #: ../source/guides/writing-pyproject-toml.rst:11 msgid "" @@ -10369,6 +10115,9 @@ msgid "" "declare which :term:`build backend` you use and which other dependencies are " "needed to build your project." msgstr "" +"A tabela ``[build-system]`` é **altamente recomendada**. Ela permite que " +"você declare qual :term:`backend de construção` você usa e quais outras " +"dependências são necessárias para construir seu projeto." #: ../source/guides/writing-pyproject-toml.rst:15 msgid "" @@ -10376,6 +10125,9 @@ msgid "" "specify your project's basic metadata, such as the dependencies, your name, " "etc." msgstr "" +"A tabela ``[project]`` é o formato que a maioria dos backends de construção " +"usa para especificar os metadados básicos do seu projeto, como as " +"dependências, seu nome, etc." #: ../source/guides/writing-pyproject-toml.rst:18 msgid "" @@ -10384,6 +10136,11 @@ msgid "" "because its contents are defined by each tool. Consult the particular tool's " "documentation to know what it can contain." msgstr "" +"A tabela ``[tool]`` possui subtabelas específicas da ferramenta, por " +"exemplo, ``[tool.hatch]``, ``[tool.black]``, ``[tool.mypy]``. Tocamos aqui " +"apenas nesta tabela porque seu conteúdo é definido por cada ferramenta. " +"Consulte a documentação da ferramenta específica para saber o que ela pode " +"conter." #: ../source/guides/writing-pyproject-toml.rst:25 msgid "" @@ -10393,6 +10150,11 @@ msgid "" "latter is understood by *most* build backends, but some build backends use a " "different format." msgstr "" +"Há uma diferença significativa entre as tabelas ``[build-system]`` e " +"``[project]``. O primeiro deve estar sempre presente, independentemente de " +"qual backend de construção você usa (já que *define* a ferramenta que você " +"usa). Este último é entendido pela *maioria* dos backends de construção mas " +"alguns backends de construção usam um formato diferente." #: ../source/guides/writing-pyproject-toml.rst:31 msgid "" @@ -10400,6 +10162,9 @@ msgid "" "backend that does not use the ``[project]`` table (it uses the ``[tool." "poetry]`` table instead)." msgstr "" +"No momento em que este artigo foi escrito (novembro de 2023), Poetry_ era um " +"backend de construção notável que não usava a tabela ``[project]`` (em vez " +"disso, ele usava a tabela ``[tool.poetry]``)." #: ../source/guides/writing-pyproject-toml.rst:35 msgid "" @@ -10410,12 +10175,16 @@ msgid "" "but the ``setup.cfg`` and ``setup.py`` formats are still valid. See :ref:" "`setup-py-deprecated`." msgstr "" +"Além disso, o backend de construção do setuptools_ oferece suporte tanto à " +"tabela ``[project]``, quanto o formato antigo em ``setup.cfg`` ou ``setup." +"py``. Para novos projetos, é recomendado usar a tabela ``[project]``, e " +"manter ``setup.py`` apenas se alguma configuração programática for " +"necessária (como construir extensões C), mas os formatos ``setup.cfg`` e " +"``setup.py`` ainda são válidos. Veja :ref:`setup-py-deprecated`." #: ../source/guides/writing-pyproject-toml.rst:45 -#, fuzzy -#| msgid "Declaring build system dependencies" msgid "Declaring the build backend" -msgstr "Declarando dependências do sistema de construção" +msgstr "Declarando o backend de construção" #: ../source/guides/writing-pyproject-toml.rst:47 msgid "" @@ -10426,6 +10195,12 @@ msgid "" "dependencies. You can also constrain the versions, e.g., ``requires = " "[\"setuptools >= 61.0\"]``." msgstr "" +"A tabela ``[build-system]`` contém uma chave ``build-backend``, que " +"especifica o backend de construção a ser usado. Ele também contém uma chave " +"``requires``, que é uma lista de dependências necessárias para construir o " +"projeto -- normalmente é apenas o pacote backend de construção, mas também " +"pode conter dependências adicionais. Você também pode restringir as versões, " +"por exemplo, ``requires = [\"setuptools >= 61.0\"]``." #: ../source/guides/writing-pyproject-toml.rst:53 msgid "" @@ -10433,16 +10208,18 @@ msgid "" "(after :ref:`choosing your build backend `). Here " "are the values for some common build backends:" msgstr "" +"Normalmente, você apenas copiará o que a documentação do seu backend de " +"construção sugere (após :ref:`escolher seu backend de construção `). Aqui estão os valores para alguns backends de construção " +"comuns:" #: ../source/guides/writing-pyproject-toml.rst:92 msgid "Static vs. dynamic metadata" -msgstr "" +msgstr "Metadados estáticos vs dinâmicos" #: ../source/guides/writing-pyproject-toml.rst:94 -#, fuzzy -#| msgid "The complete list of keys allowed in the ``[project]`` table are:" msgid "The rest of this guide is devoted to the ``[project]`` table." -msgstr "A lista completa de chaves permitidas na tabela ``[project]`` são:" +msgstr "O resto deste guia é dedicado à tabela ``[project]``." #: ../source/guides/writing-pyproject-toml.rst:96 msgid "" @@ -10450,6 +10227,9 @@ msgid "" "field. For example: ``requires-python = \">= 3.8\"``, or ``version = " "\"1.0\"``." msgstr "" +"Na maioria das vezes, você escreverá diretamente o valor de um campo " +"``[project]``. Por exemplo: ``requires-python = \">= 3.8\"``, ou ``version = " +"\"1.0\"``." #: ../source/guides/writing-pyproject-toml.rst:100 msgid "" @@ -10458,260 +10238,445 @@ msgid "" "a ``__version__`` attribute in your code, a Git tag, or similar. In such " "cases, you should mark the field as dynamic using, e.g.," msgstr "" +"No entanto, em alguns casos, é útil permitir que o backend de construção " +"calcule os metadados para você. Por exemplo: muitos backend sde construção " +"podem ler a versão de um atributo ``__version__`` em seu código, uma tag Git " +"ou similar. Nesses casos, você deve marcar o campo como dinâmico usando, por " +"exemplo," #: ../source/guides/writing-pyproject-toml.rst:111 msgid "" "When a field is dynamic, it is the build backend's responsibility to fill " "it. Consult your build backend's documentation to learn how it does it." msgstr "" +"Quando um campo é dinâmico, é da responsabilidade do backend de construção " +"preenchê-lo. Consulte a documentação do seu backend de construção para saber " +"como ele faz." #: ../source/guides/writing-pyproject-toml.rst:117 msgid "Basic information" -msgstr "" +msgstr "Informações básicas" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" +"Coloque o nome do seu projeto em PyPI. Este campo é necessário e é o único " +"campo que não pode ser marcado como dinâmico." + +#: ../source/guides/writing-pyproject-toml.rst:132 +#, fuzzy +#| msgid "" +#| "Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-" +#| "``), and/or periods (``.``), and" +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"Consistir apenas em letras ASCII, dígitos, sublinhados (``_``), hífenes (``-" +"``) e/ou pontos (``.``) e" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:136 #, fuzzy -#| msgid "The keywords for the project." +#| msgid "" +#| "Comparison of project names is case insensitive and treats arbitrarily-" +#| "long runs of underscores, hyphens, and/or periods as equal. For example, " +#| "if you register a project named ``cool-stuff``, users will be able to " +#| "download it or declare a dependency on it using any of the following " +#| "spellings::" +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"A comparação de nomes de projetos não diferencia maiúsculas de minúsculas e " +"trata sequências arbitrariamente longas de sublinhados, hífenes e/ou pontos " +"como iguais. Por exemplo, se você registrar um projeto chamado ``cool-" +"stuff``, os usuários poderão baixá-lo ou declarar uma dependência dele " +"usando qualquer uma das seguintes formas de escrever::" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." -msgstr "As palavras-chave do projeto." +msgstr "Coloque a versão do seu projeto." -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" +"Alguns especificadores de versão mais complicados como ``2020.0.0a1`` (para " +"uma versão alfa) são possíveis; veja a :ref:`especificação ` para detalhes completos." -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" +"Este campo é necessário, embora muitas vezes seja marcado como dinâmico " +"usando" -#: ../source/guides/writing-pyproject-toml.rst:155 -#, fuzzy -#| msgid "Using requirements files" +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" -msgstr "Usando arquivos de requisitos" +msgstr "Dependências e requisitos" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "``dependencies``/``optional-dependencies``" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" -msgstr "" +msgstr "Se o seu projeto tiver dependências, liste-as assim:" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" +"Veja :ref:`Especificadores de dependências ` para a " +"sintaxe completa que você pode usar para restringir versões." -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" +"Você pode querer fazer algumas de suas dependências opcionais, se forem " +"necessárias apenas para um recurso específico do seu pacote. Nesse caso, " +"coloque-os em ``optional-dependencies``." -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" +"Cada uma das chaves define um \"extra de empacotamento\". No exemplo acima, " +"pode-se usar, por exemplo, ``pip install seu-projeto-de-nome[gui]`` para " +"instalar seu projeto com suporte GUI, adicionando a dependência PyQt5." -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "``requires-python``" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" +"Isso permite que você declare a versão mínima de Python que você suporta " +"[#requires-python-upper-bounds]_." -#: ../source/guides/writing-pyproject-toml.rst:207 -#, fuzzy -#| msgid "Creating the package files" +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" -msgstr "Criando arquivos do pacote" +msgstr "Criando scripts executáveis" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" +"Para instalar um comando como parte do seu pacote, declare-o na tabela " +"``[project.scripts]``." -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" +"Neste exemplo, depois de instalar seu projeto, um comando ``spam-cli`` " +"estará disponível. Executar este comando fará o equivalente a ``from spam " +"import main_cli; main_cli()``." -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " "prevent this from happening, use the ``[project.gui-scripts]`` table instead " "of ``[project.scripts]``." msgstr "" +"No Windows, scripts empacotados desta forma precisam de um terminal, então " +"se você lançá-los de dentro de uma aplicação gráfica, eles vão fazer um pop " +"up de terminal. Para evitar que isso aconteça, use o ``[project.gui-" +"scripts]`` tabela em vez de ``[project.scripts]``." -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" +"Nesse caso, a inicialização do seu script a partir da linha de comando " +"devolve o controle imediatamente, deixando o script a ser executado em " +"segundo plano." -#: ../source/guides/writing-pyproject-toml.rst:234 -#, fuzzy -#| msgid "" -#| "TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -#| "``[project.entry-points]``)" +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -"Tipo TOML_: tabela (``[project.scripts]``, ``[project.gui-scripts]`` e " -"``[project.entry-points]``)" +"A diferença entre ``[project.scripts]`` e ``[project.gui-scripts]`` é apenas " +"relevante no Windows." -#: ../source/guides/writing-pyproject-toml.rst:240 -#, fuzzy -#| msgid "Configuring your project" +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" -msgstr "Configurando seu projeto" +msgstr "Sobre o seu projeto" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "``authors``/``maintainers``" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" +"Ambos os campos contêm listas de pessoas identificadas por um nome e/ou um " +"endereço de e-mail." + +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``description``" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:286 +#, fuzzy +#| msgid "" +#| "This should be a one-line description of your project, to show as the " +#| "\"headline\" of your project page on PyPI (`example `_)." msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" +"Esta deve ser uma descrição de uma linha do seu projeto, para mostrar como o " +"\"título\" da sua página do projeto no PyPI (`exemplo `_)." -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "``readme``" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" +"Esta é uma descrição mais longa do seu projeto, para exibir em sua página do " +"projeto em PyPI. Tipicamente, seu projeto terá um arquivo ``README.md`` ou " +"``README.rst`` e você acabou de colocar seu nome de arquivo aqui." -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" -msgstr "" - -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," -msgstr "" +msgstr "O formato do README é detectado automaticamente a partir da extensão:" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." -msgstr "" +#: ../source/guides/writing-pyproject-toml.rst:310 +#, fuzzy +#| msgid "``README.md`` → Markdown," +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → Markdown," -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:311 #, fuzzy -#| msgid "You can see the contents of the generated file like this:" +#| msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → reStructuredText (sem extensões do Sphinx)." + +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" -msgstr "Você pode ver o conteúdo do arquivo gerado assim:" +msgstr "Você também pode especificar o formato explicitamente assim:" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" +"Isto pode tomar duas formas. Você pode colocar sua licença em um arquivo, " +"tipicamente ``LICENSE`` ou ``LICENSE.txt``, e vincular esse arquivo aqui:" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" +msgstr "ou você pode escrever o nome da licença:" + +#: ../source/guides/writing-pyproject-toml.rst:341 +#, fuzzy +#| msgid "" +#| "The ``license`` argument is more typically used to indicate differences " +#| "from well-known licenses, or to include your own, unique license. As a " +#| "general rule, it's a good idea to use a standard, well-known license, " +#| "both to avoid confusion and because some organizations avoid software " +#| "whose license is unapproved." +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" msgstr "" +"O argumento ``license`` é mais comumente usado para indicar diferenças de " +"licenças conhecidas ou para incluir sua própria licença exclusiva. Como " +"regra geral, é uma boa ideia usar uma licença padrão bem conhecida, tanto " +"para evitar confusão quanto porque algumas organizações evitam software cuja " +"licença não é aprovada." + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" +"Isso ajudará a caixa de pesquisa do PyPI a sugerir o seu projeto quando as " +"pessoas procuram essas palavras-chave." -#: ../source/guides/writing-pyproject-toml.rst:337 -#, fuzzy -#| msgid "" -#| "Provide a list of classifiers that categorize your project. For a full " -#| "listing, see https://pypi.org/classifiers/." +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -"Fornece uma lista de classificadores que categorizam seu projeto. Para obter " -"uma lista completa, consulte https://pypi.org/classifiers/." - -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 -msgid "``urls``" -msgstr "``urls``" +"Uma lista de classificadores do PyPI que se aplicam ao seu projeto. " +"Verifique a `lista completa de possibilidades `_." -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:392 +#, fuzzy +#| msgid "" +#| "Although the list of classifiers is often used to declare what Python " +#| "versions a project supports, this information is only used for searching " +#| "& browsing projects on PyPI, not for installing projects. To actually " +#| "restrict what Python versions a project can be installed on, use the :ref:" +#| "`python_requires` argument." msgid "" -"A list of URLs associated with your project, displayed on the left sidebar " -"of your PyPI project page." +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." msgstr "" +"Embora a lista de classificadores seja frequentemente usada para declarar " +"quais versões do Python um projeto suporta, essas informações são usadas " +"apenas para pesquisar e navegar por projetos no PyPI, não para instalar " +"projetos. Para realmente restringir em quais versões do Python um projeto " +"pode ser instalado, use o argumento :ref:`python_requires`." -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:397 +#, fuzzy +#| msgid "" +#| "To prevent a package from being uploaded to PyPI, use the special " +#| "``'Private :: Do Not Upload'`` classifier. PyPI will always reject " +#| "packages with classifiers beginning with ``\"Private ::'``." +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"Para evitar que um pacote seja enviado para PyPI, use o classificador " +"especial ``'Private :: Do Not Upload'``. PyPI sempre rejeitará pacotes com " +"classificadores começando com ``\"Private ::'``." + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:405 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"Uma lista de URLs associadas ao seu projeto, exibida na barra lateral " +"esquerda da página do projeto PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" +"Note que se a chave contém espaços, ela precisa ser citada, por exemplo, " +"``Website = \"https://example.com\"``, mas ``\"Official Website\" = " +"\"https://example.com\"``." -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" -msgstr "" +msgstr "Plugins avançados" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" +"Alguns pacotes podem ser estendidos através de plugins. Exemplos incluem " +"Pytest_ e Pygments_. Para criar tal plugin, você precisa declará-lo em uma " +"subtabela de ``[project.entry-points]`` assim:" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." -msgstr "" +msgstr "Veja o :ref:`guia Plugin ` para mais informações." -#: ../source/guides/writing-pyproject-toml.rst:386 -#, fuzzy -#| msgid "For example" +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" -msgstr "Por exemplo" +msgstr "Um exemplo completo" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " "information regarding possible problems." msgstr "" +"Pense duas vezes antes de aplicar um limite superior como ``requires-python " +"= \"<= 3.10\"`` aqui. `Este post de blog `_ " +"contém algumas informações sobre possíveis problemas." #: ../source/index.rst:-1 msgid "" @@ -10740,24 +10705,17 @@ msgstr "" "pacotes Python com ferramentas modernas." #: ../source/index.rst:29 -#, fuzzy -#| msgid "" -#| "This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " -#| "Authority `. We happily accept any :doc:`contributions and " -#| "feedback `. 😊" msgid "" "This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " "Authority `. We happily accept :doc:`contributions and feedback " "`. 😊" msgstr "" "Este guia é mantido no `GitHub`_ pela :doc:`Python Packaging Authority `. Aceitamos toda :doc:`contribuição e feedback `. 😊" +"index>`. Aceitamos :doc:`contribuição e feedback `. 😊" #: ../source/index.rst:36 -#, fuzzy -#| msgid "Overview" msgid "Overview and Flow" -msgstr "Visão geral" +msgstr "Visão geral e fluxo" #: ../source/index.rst:40 msgid "" @@ -10765,6 +10723,10 @@ msgid "" "continuous improvement are key to success. The overview and flow sections " "provide a starting point for understanding the Python packaging ecosystem." msgstr "" +"Construir sua compreensão de empacotamento do Python é uma jornada. " +"Paciência e aprimoramento contínua são fundamentais para o sucesso. As " +"seções de visão geral e fluxo fornecem um ponto de partida para entender o " +"ecossistema de empacotamentos do Python." #: ../source/index.rst:44 msgid "" @@ -10774,18 +10736,19 @@ msgid "" "It includes what packaging is, the problems that it solves, and key " "considerations." msgstr "" +"A :doc:`overview` explica empacotamento do Python e seu uso ao preparar e " +"distribuir projetos. Esta seção ajuda você a construir compreensão sobre a " +"seleção das ferramentas e processos que são mais adequados para o seu caso " +"de uso. Inclui o que é o empacotamento, os problemas que resolve e as " +"principais considerações." #: ../source/index.rst:51 -#, fuzzy -#| msgid "" -#| "To get an overview of the flow used to publish your code, see the :doc:" -#| "`packaging flow `" msgid "" "To get an overview of the workflow used to publish your code, see :doc:" "`packaging flow `." msgstr "" -"Para obter uma visão geral do fluxo usado para publicar seu código, consulte " -"o :doc:`fluxo de empacotamento `" +"Para obter uma visão geral do fluxo de trabalho usado para publicar seu " +"código, consulte :doc:`fluxo de empacotamento `." #: ../source/index.rst:57 msgid "" @@ -10793,43 +10756,32 @@ msgid "" "time. Tutorials aim to help you succeed and provide a starting point for " "future exploration. The :doc:`tutorials/index` section includes:" msgstr "" +"Os tutoriais passam pelas etapas necessárias para completar um projeto pela " +"primeira vez. Os tutoriais visam ajudá-lo a ter sucesso e fornecer um ponto " +"de partida para a exploração futura. A seção :doc:`tutorials/index` inclui:" #: ../source/index.rst:62 -#, fuzzy -#| msgid "" -#| "To learn how to install packages, see the :doc:`tutorial on installing " -#| "packages `" msgid "" "A :doc:`tutorial on installing packages `" msgstr "" -"Para saber como instalar pacotes, veja o :doc:`tutorial sobre como instalar " -"pacotes `" +"Um :doc:`tutorial sobre como instalar pacotes `" #: ../source/index.rst:63 -#, fuzzy -#| msgid "" -#| "To learn how to manage dependencies in a version controlled project, see " -#| "the :doc:`tutorial on managing application dependencies `" msgid "" "A :doc:`tutorial on managing application dependencies ` in a version controlled project" msgstr "" -"Para saber como gerenciar dependências em um projeto controlador por versão, " -"veja o :doc:`tutorial sobre como gerenciar dependências de aplicações " -"`" +"Um :doc:`tutorial sobre como gerenciar dependências de aplicações ` em um projeto com controle de versão" #: ../source/index.rst:65 -#, fuzzy -#| msgid "" -#| "To learn how to package and distribute your projects, see the :doc:" -#| "`tutorial on packaging and distributing `" msgid "" "A :doc:`tutorial on packaging and distributing ` your project" msgstr "" -"Para saber como empacotar e distribuir seus projetos, veja o :doc:`tutorial " -"sobre como empacotar e distribuir `" +"Um :doc:`tutorial sobre como empacotar e distribuir ` seu projeto" #: ../source/index.rst:71 msgid "" @@ -10837,6 +10789,9 @@ msgid "" "users who are already familiar with Python packaging and are looking for " "specific information." msgstr "" +"Guias fornecem etapas para executar uma tarefa específica. Guias são mais " +"focados em usuários que já estão familiarizados com a empacotamento do " +"Python e estão procurando informações específicas." #: ../source/index.rst:75 msgid "" @@ -10844,32 +10799,33 @@ msgid "" "major areas: package installation; building and distributing packages; " "miscellaneous topics." msgstr "" +"A seção :doc:`guides/index` fornece instruções de \"como fazer\" em três " +"áreas principais: instalação de pacotes; construção e distribuição de " +"pacotes; diversos tópicos." #: ../source/index.rst:80 msgid "Explanations and Discussions" -msgstr "" +msgstr "Explicações e discussões" #: ../source/index.rst:82 msgid "" "The :doc:`discussions/index` section for in-depth explanations and " "discussion about topics, such as:" msgstr "" +"A seção :doc:`discussions/index` para explicações aprofundadas e discussão " +"sobre temas, tais como:" #: ../source/index.rst:85 -#, fuzzy -#| msgid "Deploying Python applications" msgid ":doc:`discussions/deploying-python-applications`" -msgstr "Fazendo deploy de aplicações Python" +msgstr ":doc:`discussions/deploying-python-applications`" #: ../source/index.rst:86 msgid ":doc:`discussions/pip-vs-easy-install`" -msgstr "" +msgstr ":doc:`discussions/pip-vs-easy-install`" #: ../source/index.rst:89 -#, fuzzy -#| msgid "References" msgid "Reference" -msgstr "Referências" +msgstr "Referência" #: ../source/index.rst:91 msgid "" @@ -10880,20 +10836,18 @@ msgstr "" "interoperabilidade de empacotamento." #: ../source/index.rst:92 -#, fuzzy -#| msgid "" -#| "Additionally, there is a list of :doc:`other projects ` " -#| "maintained by members of the Python Packaging Authority." msgid "" "The list of :doc:`other projects ` maintained by members of " "the Python Packaging Authority." msgstr "" -"Além disso, há uma lista de :doc:`outros projetos ` mantidos " -"por membros da Python Packaging Authority." +"A lista de :doc:`outros projetos ` mantidos por membros da " +"Python Packaging Authority." #: ../source/index.rst:93 msgid "The :doc:`glossary` for definitions of terms used in Python packaging." msgstr "" +"O :doc:`glossary` para definições de termos usados em empacotamento do " +"Python." #: ../source/key_projects.rst:6 msgid "Project Summaries" @@ -10943,17 +10897,12 @@ msgid "build" msgstr "construir" #: ../source/key_projects.rst:37 -#, fuzzy -#| msgid "" -#| "`Docs ` | `Issues `__ " -#| "| `GitHub `__ | `PyPI `__" msgid "" ":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" msgstr "" -"`Documentação ` | `Issues ` | `Issues `__ | `GitHub `__ | `PyPI `__" @@ -11046,27 +10995,14 @@ msgid "distutils" msgstr "distutils" #: ../source/key_projects.rst:93 -#, fuzzy -#| msgid "" -#| "The original Python packaging system, added to the standard library in " -#| "Python 2.0." msgid "" "The original Python packaging system, added to the standard library in " "Python 2.0 and removed in 3.12." msgstr "" "O sistema de empacotamento original do Python, adicionado à biblioteca " -"padrão no Python 2.0." +"padrão no Python 2.0 e removido no 3.12." #: ../source/key_projects.rst:96 -#, fuzzy -#| msgid "" -#| "Due to the challenges of maintaining a packaging system where feature " -#| "updates are tightly coupled to language runtime updates, direct usage of :" -#| "ref:`distutils` is now actively discouraged, with :ref:`Setuptools` being " -#| "the preferred replacement. :ref:`Setuptools` not only provides features " -#| "that plain :ref:`distutils` doesn't offer (such as dependency " -#| "declarations and entry point declarations), it also provides a consistent " -#| "build interface and feature set across all supported Python versions." msgid "" "Due to the challenges of maintaining a packaging system where feature " "updates are tightly coupled to language runtime updates, direct usage of :" @@ -11078,13 +11014,12 @@ msgid "" msgstr "" "Devido aos desafios de manter um sistema de empacotamento onde as " "atualizações de recursos estão fortemente acopladas às atualizações de tempo " -"de execução da linguagem, o uso direto de :ref:`distutils` agora é " -"ativamente desencorajado, com :ref:`Setuptools` sendo o substituto " -"preferido. :ref:`Setuptools` não apenas fornece recursos que o :ref:" -"`distutils` simples não oferece (como declarações de dependência e " -"declarações de ponto de entrada), ele também fornece uma interface de " -"construção consistente e conjunto de recursos em todas as versões Python " -"suportadas ." +"de execução da linguagem, o uso direto de :ref:`distutils` foi ativamente " +"desencorajado, com :ref:`Setuptools` sendo o substituto preferido. :ref:" +"`Setuptools` não apenas fornece recursos que o :ref:`distutils` simples não " +"oferece (como declarações de dependência e declarações de ponto de entrada), " +"ele também fornece uma interface de construção consistente e conjunto de " +"recursos em todas as versões Python suportadas ." #: ../source/key_projects.rst:105 msgid "" @@ -11093,6 +11028,10 @@ msgid "" "in Python 3.12. Setuptools bundles the standalone copy of distutils, and it " "is injected even on Python < 3.12 if you import setuptools first or use pip." msgstr "" +"Consequentemente, :ref:`distutils` foi descontinuado no Python 3.10 por :pep:" +"`632` e foi :doc:`removido ` da biblioteca padrão em " +"Python 3.12. Setuptools inclui a cópia autônoma de distutils, e é injetado " +"mesmo no Python < 3.12 se você importar setuptools primeiro ou usar pip." #: ../source/key_projects.rst:114 msgid "flit" @@ -11140,6 +11079,10 @@ msgid "" "com/lifter/search/pypi/flit>`__, and funds sent to the PSF and earmarked for " "PyPA usage." msgstr "" +"O pacote flit é levantado por `Matthias Bussonnier __ desde outubro de 2023 na `plataforma do tidelift __, e os fundos enviados para o PSF e " +"destinados ao uso da PyPA." #: ../source/key_projects.rst:140 msgid "hatch" @@ -11154,13 +11097,6 @@ msgstr "" "com/pypa/hatch>`__ | `PyPI `__" #: ../source/key_projects.rst:146 -#, fuzzy -#| msgid "" -#| "Hatch is a unified command-line tool meant to conveniently manage " -#| "dependencies and environment isolation for Python developers. Python " -#| "package developers use Hatch and its build backend Hatchling to " -#| "configure, version, specify dependencies for, and publish packages to " -#| "PyPI. Its plugin system allows for easily extending functionality." msgid "" "Hatch is a unified command-line tool meant to conveniently manage " "dependencies and environment isolation for Python developers. Python package " @@ -11168,12 +11104,12 @@ msgid "" "to configure, version, specify dependencies for, and publish packages to " "PyPI. Its plugin system allows for easily extending functionality." msgstr "" -"Hatch é uma ferramenta de linha de comando unificada destinada a gerenciar " -"convenientemente dependências e isolamento de ambiente para desenvolvedores " -"Python. Os desenvolvedores de pacotes Python usam o Hatch e seu backend de " -"construção para configurar, criar versões, especificar dependências e " -"publicar pacotes no PyPI. Seu sistema de plugins permite estender facilmente " -"a funcionalidade." +"Hatch é uma ferramenta de linha de comando unificada destinada para, de " +"forma conveniente, gerenciar dependências e isolamento de ambiente para " +"desenvolvedores Python. Os desenvolvedores de pacotes Python usam o Hatch e " +"seu :term:`backend de construção ` Hatchling para configurar, " +"criar versões, especificar dependências e publicar pacotes no PyPI. Seu " +"sistema de plugins permite estender facilmente a funcionalidade." #: ../source/key_projects.rst:155 msgid "packaging" @@ -11281,13 +11217,6 @@ msgstr "" "`__" #: ../source/key_projects.rst:209 -#, fuzzy -#| msgid "" -#| "Pipenv is a project that aims to bring the best of all packaging worlds " -#| "to the Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:" -#| "`virtualenv` into one single toolchain. It can autoimport ``requirements." -#| "txt`` and also check for CVEs in `Pipfile` using `safety `_." msgid "" "Pipenv is a project that aims to bring the best of all packaging worlds to " "the Python world. It harnesses :ref:`Pipfile`, :ref:`pip`, and :ref:" @@ -11297,18 +11226,11 @@ msgid "" msgstr "" "Pipenv é um projeto que visa trazer o melhor de todos os mundos de " "empacotamento para o mundo Python. Ele agrega :ref:`Pipfile`, :ref:`pip` e :" -"ref:`virtualenv` em um único conjunto de ferramentas. Possui pode " -"autoimportar ``requirements.txt`` e também pode verificar por CVEs no " -"`Pipfile` usando `safety `_." +"ref:`virtualenv` em um único conjunto de ferramentas. Ele pode autoimportar " +"``requirements.txt`` e também pode verificar por CVEs no `Pipfile` usando " +"`safety `_." #: ../source/key_projects.rst:214 -#, fuzzy -#| msgid "" -#| "Pipenv aims to help users manage environments, dependencies, and imported " -#| "packages on the command line. It also works well on Windows (which other " -#| "tools often underserve), makes and checkes file hashes, to ensure " -#| "compliance with hash-locked dependency specifiers, and eases " -#| "uninstallation of packages and dependencies." msgid "" "Pipenv aims to help users manage environments, dependencies, and imported " "packages on the command line. It also works well on Windows (which other " @@ -11346,11 +11268,11 @@ msgstr "pipx" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" -"`Documentação `__ | `GitHub `__ | `PyPI `__" +"`Documentação `__ | `GitHub `__ | `PyPI `__" #: ../source/key_projects.rst:240 msgid "" @@ -11363,13 +11285,12 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" -":doc:`Documentação ` | `Issues `__ | `GitHub `__" +":doc:`Documentação ` | `Issues `__ | `GitHub `__" #: ../source/key_projects.rst:251 msgid "This guide!" @@ -11403,10 +11324,8 @@ msgstr "" "descrições de seus pacotes serão exibidas corretamente no PyPI." #: ../source/key_projects.rst:272 -#, fuzzy -#| msgid "setuptools" msgid "Setuptools" -msgstr "setuptools" +msgstr "Setuptools" #: ../source/key_projects.rst:274 msgid "" @@ -11419,22 +11338,16 @@ msgstr "" "pypa/setuptools>`__ | `PyPI `__" #: ../source/key_projects.rst:279 -#, fuzzy -#| msgid "" -#| "setuptools (which includes ``easy_install``) is a collection of " -#| "enhancements to the Python distutils that allow you to more easily build " -#| "and distribute Python :term:`distributions `, " -#| "especially ones that have dependencies on other packages." msgid "" "Setuptools (which includes ``easy_install``) is a collection of enhancements " "to the Python distutils that allow you to more easily build and distribute " "Python :term:`distributions `, especially ones that " "have dependencies on other packages." msgstr "" -"setuptools (que inclui ``easy_install``) é uma coleção de melhorias para os " -"distutils Python que permitem a você construir e distribuir mais facilmente :" -"term:`distribuições ` Python, especialmente aquelas " -"que possuem dependências de outros pacotes." +"Setuptools (que inclui ``easy_install``) é uma coleção de melhorias para o " +"distutils do Python que permite a você construir e distribuir mais " +"facilmente :term:`distribuições ` Python, " +"especialmente aquelas que possuem dependências de outros pacotes." #: ../source/key_projects.rst:287 msgid "trove-classifiers" @@ -11453,19 +11366,17 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" "trove-classifiers é a fonte canônica para `classificadores no PyPI `_, que os mantenedores de projetos usam para " -"`descrever sistematicamente seus projetos `_ para que os " -"usuários possam encontrar melhor os projetos que correspondem às suas " +"pypi.org/classifiers/>`_, que os mantenedores de projetos usam para :ref:" +"`descrever sistematicamente seus projetos ` para " +"que os usuários possam encontrar melhor os projetos que correspondem às suas " "necessidades no PyPI." -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -11488,11 +11399,11 @@ msgstr "" "projeto hospeda discussões sobre classificadores propostos e solicitações de " "novos classificadores." -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "twine" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -11502,7 +11413,7 @@ msgstr "" "`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -11516,35 +11427,21 @@ msgstr "" "uma API web. Os desenvolvedores o usam porque é a ferramenta oficial de " "envio do PyPI, é rápida e segura, é mantida e funciona de forma confiável." -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "virtualenv" -#: ../source/key_projects.rst:332 -#, fuzzy -#| msgid "" -#| ":doc:`Docs ` | `Issues `__ | `GitHub `__ | " -#| "`PyPI `__" +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -":doc:`Documentação ` | `Issues `__ | `GitHub `__ | " -"`PyPI `__" +"`Documentação `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:337 -#, fuzzy -#| msgid "" -#| "virtualenv is a tool which uses the command-line path environment " -#| "variable to create isolated Python :term:`Virtual Environments `, much as :ref:`venv` does. virtualenv provides additional " -#| "functionality, compared to :ref:`venv`, by supporting Python 2.7 and by " -#| "providing convenient features for configuring, maintaining, duplicating, " -#| "and troubleshooting the virtual environments. For more information, see " -#| "the section on :ref:`Creating and using Virtual Environments`." +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -11554,19 +11451,19 @@ msgid "" "troubleshooting virtual environments. For more information, see the section " "on :ref:`Creating and using Virtual Environments`." msgstr "" -"virtualenv é uma ferramenta que usa a variável de ambiente de caminho de " -"linha de comando para criar :term:`Ambientes Virtuais ` " -"do Python, assim como :ref:`venv` faz. virtualenv fornece funcionalidade " -"adicional, em comparação com :ref:`venv`, oferecendo suporte ao Python 2.7 e " -"fornecendo recursos convenientes para configurar, manter, duplicar e " -"solucionar problemas de ambientes virtuais. Para obter mais informações, " -"consulte a seção sobre :ref:`Creating and using Virtual Environments`." +"virtualenv é uma ferramenta para criar :term:`Ambientes Virtuais ` isolados do Python, de forma similar ao :ref:`venv`. Ao " +"contrário de :ref:`venv`, virtualenv pode criar ambientes virtuais para " +"outras versões de Python, que ele localiza usando a variável ambiente PATH. " +"Ele também fornece recursos convenientes para configurar, manter, duplicar e " +"solucionar ambientes virtuais. Para obter mais informações, consulte a " +"seção :ref:`Creating and using Virtual Environments`." -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "Warehouse" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" @@ -11574,7 +11471,7 @@ msgstr "" "`Documentação `__ | `Issues `__ | `GitHub `__" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " @@ -11584,11 +11481,11 @@ msgstr "" "Está hospedado em `pypi.org `_. A fonte padrão para " "downloads do :ref:`pip`." -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "wheel" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -11598,7 +11495,7 @@ msgstr "" "`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " @@ -11609,7 +11506,7 @@ msgstr "" "oferece seu próprio utilitário de linha de comando para criar e instalar " "wheels." -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -11624,15 +11521,15 @@ msgstr "" "dos metadados e corrigir wheel e os metadados para vincular e incluir " "bibliotecas externas compartilhadas em um pacote." -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "Projetos não-PyPA" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "buildout" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `PyPI `__ | `GitHub `__" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -11654,15 +11551,15 @@ msgstr "" "baseadas em Python. Ele permite que você crie uma configuração de buildout e " "reproduza o mesmo software posteriormente." -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "conda" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr ":doc:`Documentação `" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -11677,7 +11574,7 @@ msgstr "" "particular no Windows onde a instalação de extensões binárias é " "frequentemente difícil ." -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " @@ -11688,7 +11585,7 @@ msgstr "" "gerenciamento de pacotes, gerenciamento de ambiente virtual e implantação de " "extensões binárias." -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -11710,11 +11607,11 @@ msgstr "" "skeleton.html>`__ é uma ferramenta para fazer pacotes Python instaláveis " "pelo conda primeiro obtendo-os em PyPI e modificando seus metadados." -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "devpi" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" @@ -11722,7 +11619,7 @@ msgstr "" "`Documentação `__ | :gh:`Issues ` | `PyPI `__" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -11734,11 +11631,11 @@ msgstr "" "atividades de empacotamento, teste e lançamento com Python. devpi também " "fornece uma interface web navegável e pesquisável." -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "enscons" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" @@ -11746,7 +11643,7 @@ msgstr "" ":gh:`Código-fonte ` | :gh:`Issues ` | " "`PyPI `__" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -11767,11 +11664,11 @@ msgstr "" "construídos automaticamente por :ref:`pip`, e wheels que são independentes " "de enscons." -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "Hashdist" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" @@ -11779,7 +11676,7 @@ msgstr "" "`Documentação `__ | `GitHub " "`__" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -11798,34 +11695,34 @@ msgstr "" "pacotes sem estado, com cache e com capacidade de distribuição. É usado por " "alguns pesquisadores, mas não tem manutenção desde 2016." -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" -msgstr "" +msgstr "Maturin" -#: ../source/key_projects.rst:484 -#, fuzzy -#| msgid "" -#| "`Docs `__ | `GitHub `__" +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -"`Documentação `__ | `GitHub " -"`__" +"`Documentação `__ | `GitHub `__" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" +"Maturin é um backend de construção para módulos de extensão Rust, também " +"escrito em Rust. Ele oferece suporte à construção de rodas para python 3.7+ " +"em Windows, Linux, macOS e FreeBSD, pode enviá-las para PyPI e tem suporte " +"básico a PyPy e GraalPy." -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "meson-python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" @@ -11833,7 +11730,7 @@ msgstr "" "`Documentação `__ | `GitHub " "`__" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -11846,17 +11743,15 @@ msgstr "" "variedade de linguagens, incluindo C, e é capaz de atender às necessidades " "das configurações de compilação mais complexas." -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "multibuild" -#: ../source/key_projects.rst:512 -#, fuzzy -#| msgid "`GitHub `__" +#: ../source/key_projects.rst:511 msgid "`GitHub `__" -msgstr "`GitHub `__" +msgstr "`GitHub `__" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" @@ -11866,11 +11761,11 @@ msgstr "" "term:`wheels ` para Linux, macOS e (menos flexível) Windows. Veja " "também :ref:`cibuildwheel`." -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "pdm" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11878,7 +11773,7 @@ msgstr "" "`Documentação `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." @@ -11887,7 +11782,7 @@ msgstr "" "`pyproject.toml` para armazenar metadados do projeto conforme definido em :" "pep:`621`." -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11895,7 +11790,7 @@ msgstr "" "`Documentação `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -11910,11 +11805,11 @@ msgstr "" "projetados para fazer a implantação de aplicações Python tão simples quanto " "``cp``." -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "pip-tools" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -11943,11 +11838,11 @@ msgstr "" "programa, atualizar todas as dependências (um recurso :ref:`pip` atualmente " "não fornece) e criar camadas de restrições para o programa obedecer." -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "piwheels" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" @@ -11955,7 +11850,7 @@ msgstr "" "`Site `__ | :doc:`Documentação ` " "| `GitHub `__" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -11967,11 +11862,11 @@ msgstr "" "otimizadas para instalação em computadores Raspberry Pi. O Raspberry Pi OS " "pré-configura pip para usar piwheels.org como um índice adicional para PyPI." -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "poetry" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -11979,7 +11874,7 @@ msgstr "" "`Documentação `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -11996,23 +11891,19 @@ msgstr "" "dependências, armazenando localmente em cache os metadados sobre as " "dependências." -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "pypiserver" -#: ../source/key_projects.rst:598 -#, fuzzy -#| msgid "" -#| "`GitHub and docs `__ | `PyPI " -#| "`__" +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -"`GitHub e documentação `__ | `PyPI " -"`__" +"`GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -12028,11 +11919,11 @@ msgstr "" "sem publicá-los publicamente. As organizações que usam o pypiserver " "geralmente baixam pacotes tanto do pypiserver quanto do PyPI." -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "PyScaffold" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -12040,7 +11931,7 @@ msgstr "" "`Documentação `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -12057,11 +11948,11 @@ msgstr "" "imediatamente. PyScaffold também pode ser usado com projetos existentes para " "tornar o empacotamento mais fácil." -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "scikit-build" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:635 -#, fuzzy -#| msgid "" -#| "Scikit-build is an improved build system generator for CPython C/C++/" -#| "Fortran/Cython extensions that integrates with :ref:`setuptools`, :ref:" -#| "`wheel` and :ref:`pip`. It internally uses `cmake `__ (available on PyPI) to provide better support for " -#| "additional compilers, build systems, cross compilation, and locating " -#| "dependencies and their associated build requirements. To speed up and " -#| "parallelize the build of large projects, the user can install `ninja " -#| "`__ (also available on PyPI)." +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -12091,48 +11972,30 @@ msgid "" "large projects, the user can install `ninja `__ (also available on PyPI)." msgstr "" -"Scikit-build é um gerador de sistema de construção aprimorado para extensões " -"C/C++/Fortran/Cython do CPython que se integra com :ref:`setuptools`, :ref:" -"`wheel` e :ref:`pip`. Ele usa internamente `cmake `__ (disponível em PyPI) para fornecer melhor suporte para " "compiladores adicionais, sistemas de construção, compilação cruzada e " -"localização de dependências e seus requisitos de construção associados. Para " +"localização de dependências e seus requisitos de compilação associados. Para " "acelerar e paralelizar a construção de grandes projetos, o usuário pode " -"instalar o `ninja `__ (também disponível no " +"instalar `ninja `__ (também disponível em " "PyPI)." -#: ../source/key_projects.rst:646 -#, fuzzy -#| msgid "scikit-build" +#: ../source/key_projects.rst:645 msgid "scikit-build-core" -msgstr "scikit-build" +msgstr "scikit-build-core" -#: ../source/key_projects.rst:648 -#, fuzzy -#| msgid "" -#| "`Docs `__ | `GitHub " -#| "`__ | `PyPI `__" +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -"`Documentação `__ | `GitHub " -"`__ | `PyPI `__" +"`Documentação `__ | " +"`GitHub `__ | `PyPI " +"`__" -#: ../source/key_projects.rst:652 -#, fuzzy -#| msgid "" -#| "Scikit-build is an improved build system generator for CPython C/C++/" -#| "Fortran/Cython extensions that integrates with :ref:`setuptools`, :ref:" -#| "`wheel` and :ref:`pip`. It internally uses `cmake `__ (available on PyPI) to provide better support for " -#| "additional compilers, build systems, cross compilation, and locating " -#| "dependencies and their associated build requirements. To speed up and " -#| "parallelize the build of large projects, the user can install `ninja " -#| "`__ (also available on PyPI)." +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ (disponível em PyPI) para fornecer melhor suporte para " -"compiladores adicionais, sistemas de construção, compilação cruzada e " -"localização de dependências e seus requisitos de construção associados. Para " -"acelerar e paralelizar a construção de grandes projetos, o usuário pode " -"instalar o `ninja `__ (também disponível no " -"PyPI)." +"Scikit-build-core é um back-end de construção para extensões CPython C/C++/" +"Fortran/Cython. Ele permite que os usuários escrevam extensões com `cmake " +"`__ (disponível no PyPI) para fornecer " +"melhor suporte para compiladores adicionais, sistemas de construção, " +"compilação cruzada e localização de dependências e suas construções " +"associadas requisitos. CMake/Ninja são baixados automaticamente do PyPI se " +"não estiverem disponíveis no sistema." -#: ../source/key_projects.rst:662 +#: ../source/key_projects.rst:661 msgid "shiv" msgstr "shiv" -#: ../source/key_projects.rst:664 +#: ../source/key_projects.rst:663 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -12163,7 +12024,7 @@ msgstr "" "`Documentação `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -12175,7 +12036,7 @@ msgstr "" "suas dependências incluídas. Seu objetivo principal é tornar a distribuição " "Python de aplicações e ferramentas de linha de comando rápida e fácil." -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__ | `Slides `__" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -12205,7 +12066,7 @@ msgstr "" "no mesmo sistema. O Spack foi projetado para construir rapidamente " "aplicações científicas de alto desempenho em clusters e supercomputadores." -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." @@ -12213,11 +12074,11 @@ msgstr "" "O Spack não está no PyPI (ainda), mas não requer instalação e pode ser usado " "imediatamente após a clonagem do GitHub." -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "zest.releaser" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -12240,15 +12101,15 @@ msgstr "" "versão de pacote, atualizando changelogs, marcando lançamentos no controle " "de fontes e enviando novos pacotes para PyPI." -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "Projetos de biblioteca padrão" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "ensurepip" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" @@ -12256,7 +12117,7 @@ msgstr "" "`Documentação `__ | " "`Issues `__" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -12268,11 +12129,11 @@ msgstr "" "Na maioria dos casos, os usuários finais não usarão este módulo, mas em vez " "disso, ele será usado durante a construção da distribuição Python." -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "venv" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" @@ -12280,7 +12141,7 @@ msgstr "" "`Documentação `__ | " "`Issues `__" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -12300,6 +12161,8 @@ msgid "" "This document is not currently updated. Previously, the document highlighted " "changes in Python packaging." msgstr "" +"Este documento não está atualizado. Anteriormente, o documento realçava as " +"mudanças no empacotamento do Python." #: ../source/news.rst:9 msgid "September 2019" @@ -12643,8 +12506,6 @@ msgstr "" "Esclarecido um classificador de descrição longa em pypi.org. (:pr:`456`)" #: ../source/news.rst:125 -#, fuzzy -#| msgid "Updated Core Metadata spec to follw PEP 556. (:pr:`412`)" msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" msgstr "" "Atualizada a especificação dos metadados principais para seguir a PEP 556. (:" @@ -12979,10 +12840,6 @@ msgstr "" "projetos hospedados (:pr:`239`)" #: ../source/news.rst:221 -#, fuzzy -#| msgid "" -#| "Swaped order of :file:`setup.py` arguments for the upload command, as " -#| "order is significant. (:pr:`260`)" msgid "" "Swapped order of :file:`setup.py` arguments for the upload command, as order " "is significant. (:pr:`260`)" @@ -13015,10 +12872,8 @@ msgid "Added :pep:`518`. (:pr:`281`)" msgstr "Adicionada a :pep:`518`. (:pr:`281`)" #: ../source/overview.rst:3 -#, fuzzy -#| msgid "An Overview of Packaging for Python" msgid "Overview of Python Packaging" -msgstr "Uma visão geral de empacotamento para Python" +msgstr "Visão geral do empacotamento para Python" #: ../source/overview.rst:7 msgid "" @@ -13216,12 +13071,6 @@ msgstr "" "Python para criar um :term:`Pacote de Distribuição` fonte, ou *sdist*." #: ../source/overview.rst:92 -#, fuzzy -#| msgid "" -#| "Python's *sdists* are compressed archives (``.tar.gz`` files) containing " -#| "one or more packages or modules. If your code is pure-Python, and you " -#| "only depend on other Python packages, you can :doc:`go here to learn more " -#| "`." msgid "" "Python's *sdists* are compressed archives (``.tar.gz`` files) containing one " "or more packages or modules. If your code is pure-Python, and you only " @@ -13230,8 +13079,8 @@ msgid "" msgstr "" "Os *sdists* do Python são arquivos compactados (arquivos ``.tar.gz``) " "contendo um ou mais pacotes ou módulos. Se seu código for puro Python e você " -"depender apenas de outros pacotes Python, você pode :doc:`clicar aqui para " -"saber mais `." +"depender apenas de outros pacotes Python, você pode consultar a " +"especificação de :ref:`source-distribution-format` para saber mais." #: ../source/overview.rst:97 msgid "" @@ -13367,13 +13216,6 @@ msgstr "" "essa suposição só é segura quando se destina a um público de desenvolvedores." #: ../source/overview.rst:163 -#, fuzzy -#| msgid "" -#| "Python's native packaging is mostly built for distributing reusable code, " -#| "called libraries, between developers. You can piggyback **tools**, or " -#| "basic applications for developers, on top of Python's library packaging, " -#| "using technologies like :doc:`setuptools entry_points `." msgid "" "Python's native packaging is mostly built for distributing reusable code, " "called libraries, between developers. You can piggyback **tools**, or basic " @@ -13385,7 +13227,7 @@ msgstr "" "código reutilizável, chamado de bibliotecas, entre os desenvolvedores. Você " "pode adicionar **ferramentas** ou aplicações básicas para desenvolvedores ao " "pacote de biblioteca do Python, usando tecnologias como :doc:`entry_points " -"do setuptools `." +"do setuptools `." #: ../source/overview.rst:169 msgid "" @@ -14050,29 +13892,17 @@ msgstr "" "os programadores pagam por usar uma das linguagens mais equilibradas e " "flexíveis disponíveis." -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "Formato de distribuição binária" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" -"O formato de distribuição binária (:term:`wheel `) foi originalmente " -"definido na :pep:`427`. A versão atual da especificação está aqui." - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "Abstrato" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -"Esta PEP descreve um formato de pacote construído para Python chamado " -"\"wheel\"." -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -14091,76 +13921,28 @@ msgstr "" "informações suficientes para espalhar seu conteúdo em seus caminhos finais a " "qualquer momento." -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "Aceitação da PEP" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" -"Esta PEP foi aceita, e a versão do wheel definida foi atualizada para 1.0, " -"por Nick Coghlan em 16 de fevereiro de 2013 [1]_" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "Justificativa" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" -"Python precisa de um formato de pacote mais fácil de instalar do que sdist. " -"Os pacotes sdist do Python são definidos e requerem os sistemas de " -"construção distutils e setuptools, executando código arbitrário para " -"construir e instalar e recompilar o código apenas para que possa ser " -"instalado em um novo virtualenv. Este sistema de combinação entre construção " -"e instalação é lento, difícil de manter e impede a inovação tanto nos " -"sistemas de construção quanto nos instaladores." - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" -"O wheel tenta remediar esses problemas fornecendo uma interface mais simples " -"entre o sistema de compilação e o instalador. O formato do pacote binário " -"wheel libera os instaladores de ter que saber sobre o sistema de compilação, " -"economiza tempo amortizando o tempo de compilação em muitas instalações e " -"elimina a necessidade de instalar um sistema de compilação no ambiente de " -"destino." - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "Detalhes" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "Instalando um wheel 'distribution-1.0-py32-none-any.whl'" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "A instalação do wheel consiste, em teoria, em duas fases:" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "Desempacotar." -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "Analisar ``distribution-1.0.dist-info/WHEEL``." -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." @@ -14168,22 +13950,22 @@ msgstr "" "Verificar se o instalador é compatível com a versão Wheel. Avisa se a versão " "secundária é maior, cancela se a versão principal é maior." -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" "Se Root-Is-Purelib == 'true', descompactar o arquivo em purelib (sites-" "packages)." -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "Caso contrário, descompactar o arquivo em platlib (site-packages)." -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "Espalhar." -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." @@ -14191,7 +13973,7 @@ msgstr "" "O arquivo descompactado inclui ``distribution-1.0.dist-info/`` e (se houver " "dados) ``distribution-1.0.data/``." -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -14205,7 +13987,7 @@ msgstr "" "platlib|headers|scripts|data)``. Os caminhos inicialmente suportados são " "obtidos de ``distutils.command.install``." -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." @@ -14213,16 +13995,16 @@ msgstr "" "Se aplicável, atualizar os scripts começando com ``#!python`` para apontar " "para o interpretador correto." -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" "Atualizar ``distribution-1.0.dist-info/RECORD`` com os caminhos instalados." -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "Remover o diretório vazio ``distribution-1.0.data``." -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" @@ -14231,15 +14013,15 @@ msgstr "" "inteligentes o suficiente para remover .pyc, mesmo que não seja mencionado " "em RECORD.)" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "Recursos de instalador recomendados" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "Reescrever ``#!python``." -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -14252,7 +14034,7 @@ msgstr "" "correto. Os instaladores do Unix podem precisar adicionar o bit +x a esses " "arquivos se o arquivo tiver sido criado em Windows." -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." @@ -14260,11 +14042,11 @@ msgstr "" "A convenção ``b'#!pythonw'`` é permitida. ``b'#!pythonw'`` indica um script " "GUI ao invés de um script de console." -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "Gerar script wrappers." -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " @@ -14274,15 +14056,15 @@ msgstr "" "acompanhados de wrappers .exe. Os instaladores Windows podem querer adicioná-" "los durante a instalação." -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "Recursos de arquivador recomendados" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "Colocar ``.dist-info`` no final do arquivo." -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -14294,15 +14076,15 @@ msgstr "" "potencialmente interessantes, incluindo a capacidade de corrigir os " "metadados sem reescrever todo o arquivo." -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "Formato de arquivos" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "Convenção de nome de arquivos" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." @@ -14310,27 +14092,27 @@ msgstr "" "O nome de arquivo do wheel é ``{distribution}-{version}(-{build tag})?-" "{python tag}-{abi tag}-{platform tag}.whl``." -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "distribution" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "Nome da distribuição (p.ex., 'django', 'pyramid')." -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "version" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "Versão da distribuição (p.ex., 1.0)." -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "build tag" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -14345,56 +14127,69 @@ msgstr "" "tupla de dois itens com o primeiro item sendo os dígitos iniciais como um " "``int``, e o segundo item sendo o restante da tag como um ``str``." -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" +"Um caso de uso comum para números de construção é reconstruir uma " +"distribuição binária devido a uma mudança no ambiente de construção, como ao " +"usar a imagem manylinux para construir distribuições usando versões de pré-" +"lançamento do CPython." -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " "ecosystem of tools and standards. A common case where a distribution would " "need to referenced externally is when resolving a security vulnerability." msgstr "" +"Os números de construção não fazem parte da versão de distribuição e, " +"portanto, são difíceis de se referir externamente, especialmente fora do " +"ecossistema do Python de ferramentas e padrões. Um caso comum em que uma " +"distribuição precisa ser referenciada externamente é quando se resolve uma " +"vulnerabilidade de segurança." -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " "distribution. Instead a **new distribution version** should be created for " "such cases." msgstr "" +"Devido a esta limitação, novas distribuições que precisam ser referenciadas " +"externamente **não devem** usar números de construção ao construir a nova " +"distribuição. Em vez disso, deve ser criada uma **nova versão de " +"distribuição** para esses casos." -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "implementação da linguagem e tag de versão" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "p.ex., 'py27', 'py2', 'py3'." -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "abi tag" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "p.ex., 'cp33m', 'abi3', 'none'." -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "platform tag" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "p.ex., 'linux_x86_64', 'any'." -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -14406,7 +14201,7 @@ msgstr "" "(qualquer implementação Python 2.7), com sem ABI (puro Python), em qualquer " "arquitetura de CPU." -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " @@ -14417,11 +14212,11 @@ msgstr "" "expressam os requisitos básicos do interpretador do pacote e são detalhadas " "na PEP 425." -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "Escape e Unicode" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " @@ -14431,7 +14226,7 @@ msgstr "" "HYPHEN-MINUS), este caractere não pode aparecer em nenhum componente. Isso é " "tratado da seguinte maneira:" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -14450,20 +14245,17 @@ msgstr "" "aceitar ``.`` (FULL STOP) e letras maiúsculas, pois estes eram permitidos " "por uma versão anterior desta especificação." -#: ../source/specifications/binary-distribution-format.rst:185 -#, fuzzy -#| msgid "" -#| "Version numbers should be normalised according to :pep:`440`. Normalised " -#| "version numbers cannot contain ``-``." +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -"Os números de versão devem ser normalizados de acordo com a :pep:`440`. Os " +"Os números de versão devem ser normalizados de acordo com a :ref:" +"`especificação de especificadores de versão `. Os " "números de versão normalizados não podem conter ``-``." -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." @@ -14471,7 +14263,7 @@ msgstr "" "Os componentes restantes não podem conter caracteres ``-``, portanto, nenhum " "escape é necessário." -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " @@ -14481,7 +14273,7 @@ msgstr "" "arquivo não contêm ``-``, pois o arquivo resultante pode não ser processado " "corretamente se contiverem." -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " @@ -14491,7 +14283,7 @@ msgstr "" "atualizadas para oferecer suporte a nomes de arquivos não ASCII, mas eles " "são suportados nesta especificação." -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " @@ -14502,11 +14294,11 @@ msgstr "" "apropriadamente, a codificação é suportada pela especificação ZIP e pelo " "``zipfile`` do Python." -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "Conteúdo dos arquivos" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " @@ -14516,7 +14308,7 @@ msgstr "" "do pacote, por exemplo, ``beaglevote`` e {version} é substituído por sua " "versão, p.ex., ``1.0.0``, consiste em:" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " @@ -14526,11 +14318,11 @@ msgstr "" "``purelib`` ou ``platlib`` conforme especificado em ``WHEEL``. ``purelib`` e " "``platlib`` são normalmente ``site-packages``." -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "``{distribution}-{version}.dist-info/`` contém metadados." -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -14542,7 +14334,7 @@ msgstr "" "subdiretório é um índice em um dicionário de caminhos de instalação (p.ex., " "``data``, ``scripts``, ``headers``, ``purelib``, ``platlib``)." -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " @@ -14553,7 +14345,7 @@ msgstr "" "python`` no momento da instalação. Eles podem ter qualquer ou nenhuma " "extensão." -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." @@ -14561,7 +14353,7 @@ msgstr "" "``{distribution}-{version}.dist-info/METADATA`` é Metadata versão 1.1 ou " "metadados de formato superior." -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" @@ -14569,11 +14361,11 @@ msgstr "" "``{distribution}-{version}.dist-info/WHEEL`` são metadados sobre p arquivo " "em si no mesmo formato \"chave: valor\"::" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "``Wheel-Version`` é o número de versão da especificação Wheel." -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." @@ -14581,7 +14373,7 @@ msgstr "" "``Generator`` é o nome e, opcionalmente, a versão do software que produziu o " "arquivo." -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " @@ -14591,7 +14383,7 @@ msgstr "" "deve ser instalado em purelib; caso contrário, a raiz deve ser instalada no " "platlib." -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." @@ -14599,14 +14391,14 @@ msgstr "" "``Tag`` são as tags de compatibilidade expandida do wheel; no exemplo, o " "nome do arquivo conteria ``py2.py3-none-any``." -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" "``Build`` é o número da construção e é omitido se não houver número da " "construção." -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " @@ -14616,7 +14408,7 @@ msgstr "" "que ele suporta, e deve falhar se Wheel-Version tiver uma versão principal " "maior do que a versão que ele suporta." -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." @@ -14624,11 +14416,11 @@ msgstr "" "O Wheel, sendo um formato de instalação destinado a funcionar em várias " "versões do Python, geralmente não inclui arquivos .pyc." -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "Wheel não contém setup.py ou setup.cfg." -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -14640,12 +14432,12 @@ msgstr "" "oferece um superconjunto da funcionalidade fornecida pelos formatos binários " "wininst e egg existentes." -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "O diretório .dist-info" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." @@ -14653,7 +14445,7 @@ msgstr "" "Os diretórios .dist-info de wheels incluem no mínimo METADATA, WHEEL e " "RECORD." -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." @@ -14661,12 +14453,12 @@ msgstr "" "METADATA são os metadados do pacote, o mesmo formato do PKG-INFO encontrado " "na raiz dos sdists." -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" "WHEEL são os metadados de wheel específicos para uma construção do pacote." -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -14681,17 +14473,17 @@ msgstr "" "wheel assinados contam com hashes fortes em RECORD para validar a " "integridade do arquivo." -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "INSTALLER e REQUESTED da PEP 376 não são incluídos no arquivo." -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" "RECORD.jws é usado para assinaturas digitais. Não é mencionado no RECORD." -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." @@ -14700,7 +14492,7 @@ msgstr "" "assinaturas S/MIME para proteger seus arquivos wheels. Não é mencionado no " "RECORD." -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -14712,11 +14504,11 @@ msgstr "" "a instalação falhará se qualquer arquivo no arquivo não for mencionado e com " "hash correto em RECORD." -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "O diretório .data" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " @@ -14726,7 +14518,7 @@ msgstr "" "para o diretório .data, nomeado como o diretório .dist-info, mas com a " "extensão .data/::" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " @@ -14736,11 +14528,11 @@ msgstr "" "documentação e assim por diante da distribuição. Durante a instalação, o " "conteúdo desses subdiretórios é movido para seus caminhos de destino." -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "Arquivos wheels assinados" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -14757,7 +14549,7 @@ msgstr "" "gerados, como arquivos .pyc, mas não RECORD, que não pode conter seu próprio " "hash. Por exemplo::" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -14769,23 +14561,29 @@ msgstr "" "outros arquivos no arquivo devem ter um hash correto em RECORD ou a " "instalação falhará." -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 +#, fuzzy +#| msgid "" +#| "If JSON web signatures are used, one or more JSON Web Signature JSON " +#| "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent " +#| "to RECORD. JWS is used to sign RECORD by including the SHA-256 hash of " +#| "RECORD as the signature's JSON payload::" msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" "Se assinaturas da web JSON forem usadas, uma ou mais assinaturas JSON Web " "Signature JSON Serialization (JWS-JS) serão armazenadas em um arquivo RECORD." "jws adjacente a RECORD. JWS é usado para assinar RECORD incluindo o hash " "SHA-256 de RECORD como a carga JSON da assinatura::" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "(O valor hash é o mesmo formato usado em RECORD.)" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." @@ -14793,7 +14591,7 @@ msgstr "" "Se RECORD.p7s for usado, ele deve conter uma assinatura de formato S/MIME " "separada de RECORD." -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -14806,15 +14604,15 @@ msgstr "" "RECORD, um verificador de assinatura separado só precisa estabelecer se " "RECORD corresponde à assinatura." -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "Veja" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "https://datatracker.ietf.org/doc/html/rfc7515" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" @@ -14822,90 +14620,26 @@ msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "https://datatracker.ietf.org/doc/html/rfc7517" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "Comparação com .egg" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" -"Wheel é um formato de instalação; ovo é importável. Os arquivos wheel não " -"precisam incluir .pyc e estão menos vinculados a uma versão ou implementação " -"específica do Python. O Wheel pode instalar pacotes (puro Python) " -"construídos com versões anteriores do Python, portanto, você nem sempre " -"precisa esperar que o empacotador os atualize." - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" -"O Wheel usa diretórios .dist-info; egg usa .egg-info. Wheel é compatível com " -"o novo mundo da empacotamento de Python e os novos conceitos que ele traz." - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" -"O Wheel tem uma convenção de nomenclatura de arquivo mais rica para o mundo " -"de múltiplas implementações de hoje. Um único arquivo de wheel pode indicar " -"sua compatibilidade com várias versões e implementações de linguagem Python, " -"ABIs e arquiteturas de sistema. Historicamente, a ABI tem sido específica " -"para uma versão do CPython, o wheel estando pronto para a ABI estável." - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" -"O wheel não causa perdas. A implementação do primeiro wheel, bdist_wheel, " -"sempre gera egg-info e, então, as converte em .whl. Também é possível " -"converter eggs existentes e distribuições de bdist_wininst." - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" -"Wheel é versionado. Cada arquivo wheel contém a versão da especificação " -"wheel e a implementação que a empacotou. Esperançosamente, a próxima " -"migração pode ser simplesmente para Wheel 2.0." - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "Wheel é uma referência a outro Python." - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "FAQ" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "Wheel define um diretório .data. Devo colocar todos os meus dados lá?" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -14921,11 +14655,11 @@ msgstr "" "resource)`` ainda que *esses* arquivos normalmente não sejam distribuídos no " "diretório ``.data`` do *wheel*." -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "Por que o wheel inclui assinaturas anexadas?" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -14939,11 +14673,11 @@ msgstr "" "os arquivos individuais podem ser verificados sem ter que baixar todo o " "arquivo." -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "Por que wheel permite assinaturas JWS?" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " @@ -14954,11 +14688,11 @@ msgstr "" "do projeto da roda. O JWS produz uma implementação puro Python concisa e " "útil." -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "Por que wheel também permite assinaturas S/MIME?" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." @@ -14966,7 +14700,7 @@ msgstr "" "Assinaturas S/MIME são permitidas para usuários que precisam ou querem usar " "uma infraestrutura de chaves públicas existente com o wheel." -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." @@ -14974,11 +14708,11 @@ msgstr "" "Pacotes assinados são apenas um bloco de construção básico em um sistema de " "atualização segura de pacotes. Wheel só fornece o bloco de construção." -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "Qual é a diferença entre \"purelib\" e \"platlib\"?" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -14990,7 +14724,7 @@ msgstr "" "puro Python em '/usr/lib/pythonX.Y/site-packages' e pacotes dependentes de " "plataforma em '/usr/lib64/pythonX.Y/site-packages'." -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -15002,7 +14736,7 @@ msgstr "" "Purelib: true\" com os mesmos arquivos na raiz, e é válido ter arquivos nas " "categorias \"purelib\" e \"platlib\"." -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " @@ -15012,11 +14746,11 @@ msgstr "" "dependendo se é puro Python ou não e esses arquivos devem estar na raiz com " "a configuração apropriada fornecida para \"Root-is-purelib\"." -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "É possível importar código Python diretamente de um arquivo wheel?" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -15030,7 +14764,7 @@ msgstr "" "``sys.path``. No entanto, embora esse comportamento seja uma consequência " "natural do design do formato, não é recomendável confiar nele." -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -15049,7 +14783,7 @@ msgstr "" "segurança, ou integração completa com o maquinário de construção padrão para " "extensões C, publicando arquivos de cabeçalho no local apropriado)." -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -15083,7 +14817,7 @@ msgstr "" "abstratos internamente, a interface com componentes externos ainda pode " "exigir a disponibilidade de um arquivo real no disco." -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -15097,15 +14831,33 @@ msgstr "" "esteja ciente de que muitos projetos exigirão que uma falha seja reproduzida " "com um pacote totalmente instalado antes de aceitá-lo como um bug genuíno." -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" -msgstr "Alterações" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "Histórico" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." +msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" -msgstr "Desde a :pep:`427`, esta especificação mudou da seguinte forma:" +#: ../source/specifications/binary-distribution-format.rst:423 +#, fuzzy +#| msgid "" +#| "The following changes were made based on feedback after its initial " +#| "implementation:" +msgid "The following changes were applied since the initial version:" +msgstr "" +"As seguintes alterações foram feitas com base no feedback após sua " +"implementação inicial:" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." @@ -15114,36 +14866,19 @@ msgstr "" "para alinhá-las com o que as ferramentas populares realmente fazem " "(fevereiro de 2021)." -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" -"Aceitação da PEP (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "Apêndice" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "Exemplo de implementação de urlsafe-base64-nopad::" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "Diretos autorais" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "Este documento foi colocado em domínio público." - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "Especificações de metadados principais" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" @@ -15151,23 +14886,23 @@ msgstr "" "Os campos definidos nas especificações a seguir devem ser considerados " "válidos, completos e não sujeitos a alterações. Os campos obrigatórios são:" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "``Name``" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "Todos os outros campos são opcionais." -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, a versão principal é o " +"valor antes do primeiro ponto)." -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " @@ -15268,38 +14997,38 @@ msgstr "" "escolher produzir metadados de distribuição usando a versão de metadados " "mais baixa que inclui todos os campos necessários." -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "Exemplo::" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "Nome" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "Adicionadas restrições adicionais ao formato da :pep:`508`" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -15313,36 +15042,33 @@ msgstr "" "Os nomes de distribuição são limitados àqueles que correspondem ao seguinte " "regex (executado com ``re.IGNORECASE``)::" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -"Para propósitos de comparação, os nomes devem ser :ref:` normalizados ` antes da comparação." -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "Versão" -#: ../source/specifications/core-metadata.rst:97 -#, fuzzy -#| msgid "" -#| "A string containing the distribution's version number. This field must " -#| "be in the format specified in :pep:`440`." +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" "Uma string contendo o número da versão da distribuição. Este campo deve " -"estar no formato especificado na :pep:`440`." +"estar no formato especificado na :ref:`especificação de especificadores de " +"versão `." -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "Dynamic (vários usos)" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " @@ -15352,7 +15078,7 @@ msgstr "" "dos campos ``Name``, ``Version`` e ``Metadata-Version`` não podem ser " "especificados neste campo." -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" @@ -15360,7 +15086,7 @@ msgstr "" "Quando encontrados nos metadados de uma distribuição fonte, as seguintes " "regras se aplicam:" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -15372,7 +15098,7 @@ msgstr "" "sdist. Se o campo não estiver no sdist e não estiver marcado como " "``Dynamic``, ele NÃO DEVE estar presente no wheel." -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." @@ -15381,7 +15107,7 @@ msgstr "" "válido em um wheel construído a partir do sdist (incluindo não estar " "presente)." -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " @@ -15392,7 +15118,7 @@ msgstr "" "seja, não há restrições especiais sobre os metadados dos wheels construídos " "a partir do sdist)." -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -15404,17 +15130,17 @@ msgstr "" "de construção do wheel, e pode não ser o mesmo que o valor no sdist ou em " "outros wheels para o projeto." -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" "Detalhes completos da semântica de ``Dynamic`` são descritos na :pep:`643`." -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "Platform (vários usos)" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " @@ -15424,11 +15150,23 @@ msgstr "" "suportado pela distribuição que não está listado nos classificadores Trove " "de \"Operating System\". Veja \"Classifier\" abaixo." -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "Exemplos::" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "Supported-Platform (vários usos)" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -15440,19 +15178,19 @@ msgstr "" "e a CPU para os quais a distribuição binária foi compilada. A semântica do " "campo Supported-Platform não é especificada nesta PEP." -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "Summary" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "Um resumo de uma linha do que a distribuição faz." -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "Este campo pode ser especificado no corpo da mensagem." -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -15464,7 +15202,7 @@ msgstr "" "este campo, embora as pessoas não devam incluir seu manual de instruções " "como a descrição." -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -15476,7 +15214,7 @@ msgstr "" "opcional; os programas também podem exibir o conteúdo do campo como está. " "Isso significa que os autores devem ser conservadores na marcação que usam." -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -15489,7 +15227,7 @@ msgstr "" "campo Description é codificado em um campo dobrado que pode ser interpretado " "pelo analisador RFC822 [2]_." -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " @@ -15499,7 +15237,7 @@ msgstr "" "espaços e um caractere pipe devem ser substituídos por um único CRLF quando " "o campo é desdobrado usando um leitor de RFC822." -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " @@ -15509,11 +15247,11 @@ msgstr "" "mensagem (ou seja, após uma linha completamente em branco após os " "cabeçalhos, sem recuo ou outra formatação especial necessária)." -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "Description-Content-Type" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." @@ -15522,7 +15260,7 @@ msgstr "" "da distribuição, para que as ferramentas possam renderizar a descrição de " "maneira inteligente." -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `_). Resumidamente, isso significa que ele tem uma parte do ``tipo/" "subtipo`` e então pode opcionalmente ter uma série de parâmetros:" -#: ../source/specifications/core-metadata.rst:269 +#: ../source/specifications/core-metadata.rst:271 msgid "Format::" msgstr "Formato::" -#: ../source/specifications/core-metadata.rst:273 +#: ../source/specifications/core-metadata.rst:275 msgid "The ``type/subtype`` part has only a few legal values:" msgstr "A parta ``tipo/subtipo`` tem apenas alguns poucos valores válidos:" -#: ../source/specifications/core-metadata.rst:275 +#: ../source/specifications/core-metadata.rst:277 msgid "``text/plain``" msgstr "``text/plain``" -#: ../source/specifications/core-metadata.rst:276 +#: ../source/specifications/core-metadata.rst:278 msgid "``text/x-rst``" msgstr "``text/x-rst``" -#: ../source/specifications/core-metadata.rst:277 +#: ../source/specifications/core-metadata.rst:279 msgid "``text/markdown``" msgstr "``text/markdown``" -#: ../source/specifications/core-metadata.rst:279 +#: ../source/specifications/core-metadata.rst:281 msgid "" "The ``charset`` parameter can be used to specify the character encoding of " "the description. The only legal value is ``UTF-8``. If omitted, it is " @@ -15594,7 +15332,7 @@ msgstr "" "caracteres da descrição. O único valor válido é ``UTF-8``. Se omitido, é " "considerado ``UTF-8``." -#: ../source/specifications/core-metadata.rst:283 +#: ../source/specifications/core-metadata.rst:285 msgid "" "Other parameters might be specific to the chosen subtype. For example, for " "the ``markdown`` subtype, there is an optional ``variant`` parameter that " @@ -15607,17 +15345,15 @@ msgstr "" "é ``GFM`` se não for especificado). Atualmente, duas variantes são " "reconhecidas:" -#: ../source/specifications/core-metadata.rst:288 -#, fuzzy -#| msgid "``GFM`` for :rfc:`Github-flavored Markdown <7764#section-3.2>`" +#: ../source/specifications/core-metadata.rst:290 msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" -msgstr "``GFM`` para :rfc:`Github-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` para :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "``CommonMark`` para :rfc:`CommonMark <7764#section-3.5>`" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " @@ -15627,7 +15363,7 @@ msgstr "" "tentar renderizá-lo como ``text/x-rst; charset=UTF-8`` e volta para ``text/" "plain`` se não for válido primeiro." -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " @@ -15637,7 +15373,7 @@ msgstr "" "de conteúdo presumido ser ``text/plain`` (embora PyPI provavelmente rejeite " "qualquer coisa com um valor não reconhecido)." -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " @@ -15647,7 +15383,7 @@ msgstr "" "for especificado ou estiver definido com um valor não reconhecido, então a " "presume-se ``variant`` ser ``GFM`` ." -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " @@ -15656,11 +15392,11 @@ msgstr "" "Portanto, para o último exemplo acima, o ``charset`` padrão é ``UTF-8`` e o " "``variant`` padrão ``GFM`` e, portanto, é equivalente ao exemplo anterior." -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "Keywords" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." @@ -15668,7 +15404,7 @@ msgstr "" "Uma lista de palavras-chave adicionais, separadas por vírgulas, a serem " "usadas para auxiliar na busca pela distribuição em um catálogo maior." -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -15680,19 +15416,19 @@ msgstr "" "foram amplamente utilizadas por muitos anos, então era mais fácil atualizar " "a especificação para corresponder ao padrão de fato." -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "Home-page" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "Uma string contendo a URL para a página da distribuição." -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "Download-URL" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" @@ -15702,11 +15438,11 @@ msgstr "" "ser baixada. (Isso significa que a URL não pode ser algo como \".../" "BeagleVote-latest.tgz\", mas deve ser \".../BeagleVote-0.45.tgz\".)" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "Author" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." @@ -15714,11 +15450,11 @@ msgstr "" "Um string contendo o nome do autor, no mínimo; informações de contato " "adicionais podem ser fornecidas." -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "Author-email" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." @@ -15726,8 +15462,8 @@ msgstr "" "Uma string contendo o endereço de e-mail do autor. Ela pode conter um nome e " "endereço de e-mail nas formas válidos para um cabeçalho ``From:`` do RFC-822." -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" @@ -15735,11 +15471,11 @@ msgstr "" "De acordo com RFC-822, este campo pode conter vários endereços de e-mail " "separados por vírgula::" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Mantenedor" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." @@ -15747,7 +15483,7 @@ msgstr "" "Uma string contendo o nome do mantenedor, no mínimo; informações de contato " "adicionais podem ser fornecidas." -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " @@ -15757,11 +15493,11 @@ msgstr "" "por alguém que não seja o autor original: ele deve ser omitido se for " "idêntico a ``Author``." -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "Maintainer-email" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." @@ -15770,7 +15506,7 @@ msgstr "" "nome e endereço de e-mail nas formas válidas para um cabeçalho ``From:`` do " "RFC-822." -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " @@ -15780,11 +15516,11 @@ msgstr "" "por alguém que não seja o autor original: ele deve ser omitido se for " "idêntico a ``Author-email``." -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "License" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -15799,11 +15535,11 @@ msgstr "" "especificar uma versão particular de uma licença que é nomeada através do " "campo ``Classifier``, ou para indicar uma variação ou exceção a tal licença." -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "Classifier (vários usos)" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -15815,23 +15551,23 @@ msgstr "" "Package Index publica uma lista dinâmica de `classificadores atualmente " "definidos `__." -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" "Este campo pode ser seguido por um marcador de ambiente após um ponto e " "vírgula." -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "Requires-Dist (vários usos)" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." @@ -15839,7 +15575,7 @@ msgstr "" "A especificação do formato de campo foi relaxada para aceitar a sintaxe " "usada por ferramentas de publicação populares." -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." @@ -15847,11 +15583,11 @@ msgstr "" "Cada entrada contém uma string nomeando algum outro projeto distutils " "requerido por esta distribuição." -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "O formato de uma string de requisito contém de uma a quatro partes:" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." @@ -15859,7 +15595,7 @@ msgstr "" "Um nome de projeto, no mesmo formato do campo ``Name:``. A única parte " "obrigatória." -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -15871,7 +15607,7 @@ msgstr "" "precisar de dependências extras. Os nomes DEVEM estar em conformidade com as " "restrições especificadas pelo campo ``Provides-Extra:``." -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." @@ -15880,7 +15616,7 @@ msgstr "" "aceitar parênteses opcionais em torno disso, mas as ferramentas que o geram " "não devem usar parênteses." -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." @@ -15888,11 +15624,11 @@ msgstr "" "Um marcador de ambiente após um ponto e vírgula. Isso significa que o " "requisito só é necessário nas condições especificadas." -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "Veja a :pep:`508` para detalhes completos do formato permitido." -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." @@ -15900,7 +15636,7 @@ msgstr "" "Os nomes dos projetos devem corresponder aos nomes encontrados no `Python " "Package Index`_." -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." @@ -15908,45 +15644,43 @@ msgstr "" "Os especificadores de versão devem seguir as regras descritas em :doc:" "`version-specifiers`." -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "Requires-Python" -#: ../source/specifications/core-metadata.rst:553 -#, fuzzy -#| msgid "" -#| "This field specifies the Python version(s) that the distribution is " -#| "guaranteed to be compatible with. Installation tools may look at this " -#| "when picking which version of a project to install." +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" "Este campo especifica a(s) versão(ões) do Python com as quais a distribuição " -"tem garantia de compatibilidade. As ferramentas de instalação podem observar " -"isso ao escolher qual versão de um projeto instalar." +"é compatível. As ferramentas de instalação podem observar isso ao escolher " +"qual versão de um projeto instalar." -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" "O valor deve estar no formato especificado em :doc:`version-specifiers`." -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 +#, fuzzy msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" +"Por exemplo, se uma distribuição usa :ref:`f-strings ` " +"então pode impedir a instalação em Python < 3.6 especificando::" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "Este campo não pode ser seguido por um marcador de ambiente." -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "Requires-External (vários usos)" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -15958,7 +15692,7 @@ msgstr "" "uma dica para os mantenedores do projeto downstream, e não tem semântica que " "seja significativa para a distribuição ``distutils``." -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." @@ -15966,13 +15700,7 @@ msgstr "" "O formato de uma string de requisito é o nome de uma dependência externa, " "opcionalmente seguido por uma declaração de versão entre parênteses." -#: ../source/specifications/core-metadata.rst:587 -#, fuzzy -#| msgid "" -#| "Because they refer to non-Python software releases, version numbers for " -#| "this field are **not** required to conform to the format specified in :" -#| "pep:`440`: they should correspond to the version scheme used by the " -#| "external dependency." +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -15981,19 +15709,20 @@ msgid "" msgstr "" "Como eles se referem a lançamentos de software não-Python, os números de " "versão para este campo **não** são obrigados a estar em conformidade com o " -"formato especificado na :pep:`440`: eles devem corresponder ao esquema de " -"versão usado pela dependência externa." +"formato especificado na :ref:`especificação de especificadores de versão " +"`: eles devem corresponder ao esquema de versão usado " +"pela dependência externa." -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" "Observe que não há uma regra específica sobre as strings a serem usadas." -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "Project-URL (vários usos)" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." @@ -16001,15 +15730,15 @@ msgstr "" "Uma string contendo uma URL navegável para o projeto e um rótulo para ele, " "separados por uma vírgula." -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "O rótulo é um texto livre limitado a 32 caracteres." -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "Provides-Extra (vários usos)" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " @@ -16020,7 +15749,7 @@ msgstr "" "restrições de valor foram alinhadas com ``Name:`` e as regras de " "normalização foram introduzidas." -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -16034,7 +15763,7 @@ msgstr "" "hífen. Os nomes são limitados àqueles que correspondem ao seguinte regex " "(que elimina ambiguidade)::" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." @@ -16042,7 +15771,7 @@ msgstr "" "O nome especificado pode ser usado para tornar uma dependência condicional " "ao fato de o recurso opcional ter sido solicitado." -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -16054,7 +15783,7 @@ msgstr "" "(,). Os requisitos são avaliados para cada recurso solicitado e adicionados " "ao conjunto de requisitos para a distribuição." -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " @@ -16064,7 +15793,7 @@ msgstr "" "dependências que são necessárias para executar testes automatizados e gerar " "documentação, respectivamente." -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." @@ -16072,7 +15801,7 @@ msgstr "" "É válido especificar ``Provides-Extra:`` sem referenciá-lo em qualquer " "``Requer-Dist:``." -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -16084,7 +15813,7 @@ msgstr "" "realizar comparações. Ferramentas que escrevem metadados DEVEM gerar um erro " "se duas entradas ``Provides-Extra:`` colidirem após serem normalizadas." -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -16101,11 +15830,11 @@ msgstr "" "optar por gerar um erro ao ler um nome inválido para versões de metadados " "mais antigas." -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "Campos raramente usados" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -16117,7 +15846,7 @@ msgstr "" "Linux, e não está claro como as ferramentas devem interpretá-los no contexto " "de um servidor de indexação aberto, como `PyPI `__." -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -16133,11 +15862,11 @@ msgstr "" "informativos e também podem ser usados para o propósito originalmente " "pretendido em combinação com um repositório de pacotes com curadoria." -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "Provides-Dist (vários usos)" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " @@ -16147,7 +15876,7 @@ msgstr "" "contido nesta distribuição. Este campo *deve* incluir o projeto identificado " "no campo ``Name``, seguido da versão: Nome (Versão)." -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -16162,7 +15891,7 @@ msgstr "" "Instalar tal distribuição de código-fonte satisfaz os requisitos para " "``ZODB`` e ``transaction``." -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -16180,7 +15909,7 @@ msgstr "" "declarar que fornece ``ORM-bindings``, permitindo que outros projetos " "dependam apenas de ter no máximo um deles instalado." -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " @@ -16190,11 +15919,11 @@ msgstr "" "descritas em :doc:`version-specifiers`. O número da versão da distribuição " "estará implícito se nenhum for especificado." -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "Obsoletes-Dist (vários usos)" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " @@ -16204,7 +15933,7 @@ msgstr "" "distutils que esta distribuição torna obsoleta, o que significa que os dois " "projetos não devem ser instalados ao mesmo tempo." -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." @@ -16212,7 +15941,7 @@ msgstr "" "Declarações de versão podem ser fornecidas. Os números de versão devem estar " "no formato especificado em :doc:`version-specifiers`." -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " @@ -16222,48 +15951,37 @@ msgstr "" "projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando " "você instala o Torqued Python, a distribuição Gorgon deve ser removida." -#: ../source/specifications/core-metadata.rst:765 -#, fuzzy -#| msgid "Rarely Used Fields" +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" -msgstr "Campos raramente usados" +msgstr "Campos descontinuados" -#: ../source/specifications/core-metadata.rst:768 -#, fuzzy -#| msgid "Requirements" +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" -msgstr "Requisitos" +msgstr "Requires" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" -msgstr "" +msgstr "em favor de ``Requires-Dist``" -#: ../source/specifications/core-metadata.rst:774 -#, fuzzy -#| msgid "" -#| "Each entry contains a string naming some other distutils project required " -#| "by this distribution." +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -"Cada entrada contém uma string nomeando algum outro projeto distutils " -"requerido por esta distribuição." +"Cada entrada contém uma string descrevendo algum outro módulo ou pacote " +"requerido por este pacote." -#: ../source/specifications/core-metadata.rst:777 -#, fuzzy -#| msgid "" -#| "The format of a requirement string is a name of an external dependency, " -#| "optionally followed by a version declaration within parentheses." +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -"O formato de uma string de requisito é o nome de uma dependência externa, " -"opcionalmente seguido por uma declaração de versão entre parênteses." +"O formato de uma string de requisito é idêntico ao de um nome de módulo ou " +"pacote utilizável com a instrução ``import``, opcionalmente seguida por uma " +"declaração de versão dentro de parênteses." -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -16273,34 +15991,47 @@ msgid "" "on the end consisting of the letter 'a' or 'b' followed by a number. Example " "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" +"Uma declaração de versão é uma série de operadores condicionais e números de " +"versão, separados por vírgulas. Os operadores condicionais devem ser um dos " +"\"<\", \">\"', \"<=\", \">=\", \"=\", e \"!=\". Os números da versão devem " +"estar no formato aceito pela classe ``distutils.version.StrictVersion``: " +"dois ou três componentes numéricos separados por ponto, com uma tag \"pre-" +"release\" opcional no final que consiste na letra 'a' ou 'b' seguida de um " +"número. Os números da versão do exemplo são \"1.0\", \"2.3a2\", \"1.3.99\"." -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" +"Qualquer número de operadores condicionais pode ser especificado, por " +"exemplo, a string \">1.0, !=1.3.4, <2.0\" é uma declaração de versão válida." -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" +"Todos os seguintes são possíveis strings de requisito: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" +"Não há nenhuma lista canônica de quais strings devem ser usadas; a " +"comunidade Python é livre para escolher seus próprios padrões." -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" -msgstr "" +msgstr "Provides" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" -msgstr "" +msgstr "em favor de ``Provides-Dist``" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -16308,38 +16039,31 @@ msgid "" "(without a comparison operator); the package’s version number will be " "implied if none is specified." msgstr "" +"Cada entrada contém uma string descrevendo um pacote ou módulo que será " +"fornecido por este pacote uma vez instalado. Essas strings devem " +"corresponder às usadas nos campos Requirements. Uma declaração de versão " +"pode ser fornecida (sem um operador de comparação); o número de versão do " +"pacote será implícito se nenhum for especificado." -#: ../source/specifications/core-metadata.rst:830 -#, fuzzy -#| msgid "Obsolete" +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" -msgstr "Obsoleto" +msgstr "Obsoletes" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" -msgstr "" +msgstr "em favor de ``Obsoletes-Dist``" -#: ../source/specifications/core-metadata.rst:836 -#, fuzzy -#| msgid "" -#| "Each entry contains a string describing a distutils project's " -#| "distribution which this distribution renders obsolete, meaning that the " -#| "two projects should not be installed at the same time." +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -"Cada entrada contém uma string que descreve a distribuição de um projeto " -"distutils que esta distribuição torna obsoleta, o que significa que os dois " -"projetos não devem ser instalados ao mesmo tempo." +"Cada entrada contém uma string descrevendo um pacote ou módulo que este " +"pacote torna obsoleta, o que significa que os dois projetos não devem ser " +"instalados ao mesmo tempo. Declarações de versão pode ser fornecidas." -#: ../source/specifications/core-metadata.rst:840 -#, fuzzy -#| msgid "" -#| "The most common use of this field will be in case a project name changes, " -#| "e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " -#| "Torqued Python, the Gorgon distribution should be removed." +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " @@ -16347,4112 +16071,4048 @@ msgid "" msgstr "" "O uso mais comum deste campo será no caso de alteração do nome de um " "projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando " -"você instala o Torqued Python, a distribuição Gorgon deve ser removida." +"você instala o Torqued Python, o pacote Gorgon deve ser removido." -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "Marcação reStructuredText: https://docutils.sourceforge.io/" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" -msgstr "Declarando dependências do sistema de construção" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "Especificadores de dependência" -#: ../source/specifications/declaring-build-dependencies.rst:8 -#, fuzzy -#| msgid "" -#| "`pyproject.toml` is a build system independent file format defined in :" -#| "pep:`518` that projects may provide in order to declare any Python level " -#| "dependencies that must be installed in order to run the project's build " -#| "system successfully." +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" -"`pyproject.toml` é um formato de arquivo independente do sistema de " -"construção definido na :pep:`518` que os projetos podem fornecer para " -"declarar quaisquer dependências de nível Python que devem ser instaladas " -"para executar o sistema de construção do projeto com sucesso." - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" +"O trabalho de uma dependência é permitir que ferramentas como pip [#pip]_ " +"encontrem o pacote certo para instalar. Às vezes, isso é muito vago -- " +"apenas especificando um nome -- e, às vezes, muito específico -- referindo-" +"se a um arquivo específico a ser instalado. Às vezes, as dependências são " +"relevantes apenas em uma plataforma, ou apenas algumas versões são " +"aceitáveis, então a linguagem permite descrever todos esses casos." -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 +#, fuzzy msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" +"A linguagem definida é um formato compacto baseado em linha que já está em " +"uso generalizado em arquivos de requisitos pip, embora não especifiquemos a " +"manipulação de opção de linha de comando que esses arquivos permitem. Há uma " +"ressalva: o formulário de referência de URL, especificado em :pep:`440`, não " +"é realmente implementado em pip, mas como :pep:`440` é aceito, usamos esse " +"formato em vez do formato nativo atual de pip." -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Especificação" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" +"Todos os recursos do idioma mostrados com uma pesquisa baseada em nome ::" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" +msgstr "Uma pesquisa baseada em URL mínima ::" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "Conceitos" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" +"Uma especificação de dependência sempre especifica um nome de distribuição. " +"Pode incluir extras, que expandem as dependências da distribuição nomeada " +"para habilitar recursos opcionais. A versão instalada pode ser controlada " +"usando limites de versão ou fornecendo a URL para um artefato específico " +"para instalação. Finalmente, a dependência pode ser condicionada usando " +"marcadores de ambiente." -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "Gramática" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" +"Primeiro, abordamos brevemente a gramática e, posteriormente, detalhamos a " +"semântica de cada seção." -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" -msgstr "Declarando os metadados do projeto" - -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -"A :pep:`621` especifica como escrever :ref:`metadados principais ` de um projeto em um arquivo ``pyproject.toml`` para ferramentas " -"relacionadas ao empacotamento consumirem. Ele define a seguinte " -"especificação como a fonte canônica para o formato usado." +"Uma especificação de distribuição é escrita em texto ASCII. Usamos uma " +"gramática de parsley [#parsley]_ para fornecer uma gramática precisa. Espera-" +"se que a especificação seja incorporada a um sistema maior que ofereça " +"enquadramento, como comentários, suporte a várias linhas por meio de " +"continuações ou outros recursos semelhantes." -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" +"A gramática completa, incluindo anotações para construir uma árvore de " +"análise útil, está incluída no final deste documento." -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Especificação" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -"Existem dois tipos de metadados: *estáticos* e *dinâmicos*. Metadados " -"estáticos são especificados diretamente no arquivo ``pyproject.toml`` e não " -"podem ser especificados ou alterados por uma ferramenta (isso inclui dados " -"*referenciados* pelo metadados, por exemplo, o conteúdo de arquivos " -"referenciados pelos metadados). Os metadados dinâmicos são listados por meio " -"da chave ``dynamic`` (definido posteriormente nesta especificação) e " -"representam os metadados que uma ferramenta fornecerá posteriormente." - -#: ../source/specifications/declaring-project-metadata.rst:30 -#, fuzzy -#| msgid "" -#| "The keys defined in this specification MUST be in a table named " -#| "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -#| "which are not defined by this specification. For tools wishing to store " -#| "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " -#| "table as defined in the :ref:`build dependency declaration specification " -#| "`. The lack of a ``[project]`` table " -#| "implicitly means the build back-end will dynamically provide all keys." -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" -"As chaves definidas nesta especificação DEVEM estar em uma tabela chamada " -"``[project]`` no arquivo ``pyproject.toml``. Nenhuma ferramenta pode " -"adicionar chaves a esta tabela que não sejam definidas por esta " -"especificação. Para ferramentas que desejam armazenar suas próprias " -"configurações em ``pyproject.toml``, elas podem usar a tabela ``[tool]`` " -"conforme definido na :ref:`especificação da declaração de dependências de " -"construção `. A falta de uma tabela " -"``[project]`` implicitamente significa que o backend da construção fornecerá " -"dinamicamente todas as chaves." - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" -msgstr "As únicas chaves que precisam ser definidos estaticamente são:" +"As versões podem ser especificadas de acordo com as regras da :ref:" +"`especificação de especificadores de versão `. (Nota: " +"URI é definido em :rfc:`std-66 <3986>`)::" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -"As chaves que são obrigatórias, mas podem ser especificadas estaticamente " -"*ou* listadas como dinâmicas são:" +"Os marcadores de ambiente permitem que uma especificação só tenha efeito em " +"alguns ambientes ::" -#: ../source/specifications/declaring-project-metadata.rst:48 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -"Todas as outras chaves são consideradas opcionais e podem ser especificadas " -"estaticamente, listadas como dinâmicas ou não especificadas." - -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" -msgstr "A lista completa de chaves permitidas na tabela ``[project]`` são:" - -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" -msgstr "``authors``" - -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" -msgstr "``dependencies``" - -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" -msgstr "``dynamic``" +"Componentes opcionais de uma distribuição podem ser especificados usando o " +"campo extras::" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" -msgstr "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "Restrições de nomes para extras são definidas na :pep:`685`." -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" -msgstr "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" +msgstr "Fornecendo uma regra para requisitos baseados em nome ::" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" -msgstr "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" +msgstr "E uma regra para especificações de referência direta ::" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" -msgstr "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" +msgstr "Levando à regra unificada que pode especificar uma dependência.::" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "Tipo TOML_: string" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" +msgstr "Espaço em branco" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:128 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Name `" +"O espaço em branco sem quebra de linha é principalmente opcional, sem " +"significado semântico. A única exceção é detectar o fim de um requisito de " +"URL." -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." -msgstr "O nome do projeto." +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" +msgstr "Nomes" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -"As ferramentas DEVEM :ref:`normalizar ` este nome, " -"conforme especificado por :pep:`503`, assim que for lido para consistência " -"interna." +"Nomes de distribuição Python são atualmente definidos na :pep:`345`. Os " +"nomes atuam como o identificador primário para distribuições. Eles estão " +"presentes em todas as especificações de dependência e são suficientes para " +"serem uma especificação por conta própria. No entanto, PyPI impõe restrições " +"estritas aos nomes: eles devem corresponder a uma regex que não diferencie " +"maiúsculas de minúsculas ou não serão aceitos. Assim, neste documento, " +"limitamos os valores aceitáveis para identificadores a essa regex. Uma " +"redefinição completa do nome pode ocorrer em um futuro PEP de metadados. A " +"regex (executada com re.IGNORECASE) é ::" -#: ../source/specifications/declaring-project-metadata.rst:88 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" -msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Version `" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" +msgstr "Extras" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" +"Um extra é uma parte opcional de uma distribuição. As distribuições podem " +"especificar quantos extras desejarem, e cada extra resulta na declaração de " +"dependências adicionais da distribuição **quando** o extra é usado em uma " +"especificação de dependência. Por exemplo ::" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "Os usuários DEVEM preferir especificar versões já normalizadas." - -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Summary `" +"União de extras nas dependências que definem com as dependências da " +"distribuição à qual estão anexados. O exemplo acima resultaria na instalação " +"de solicitações e nas próprias dependências das solicitações, além de " +"quaisquer dependências listadas no extra de \"security\" das solicitações." -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." -msgstr "A descrição resumida do projeto." +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "Se vários extras forem listados, todas as dependências serão unidas." -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" -msgstr "Tipo TOML_: string ou tabela" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" +msgstr "Versões" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -"Campos correspondente dos :ref:`metadados principais `: :ref:" -"`Description ` e :ref:`Description-Content-Type " -"`" +"Consulte a :ref:`especificação de especificadores de versão ` para obter mais detalhes sobre números de versão e comparações " +"de versões. As especificações de versão limitam as versões de uma " +"distribuição que podem ser usadas. Elas se aplicam apenas a distribuições " +"pesquisadas pelo nome, e não por meio de uma URL. A comparação de versões " +"também é usada no recurso de marcadores. Os colchetes opcionais em torno de " +"uma versão estão presentes para compatibilidade com :pep:`345`, mas não " +"devem ser gerados, apenas aceitos." -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." -msgstr "A descrição completa do projeto (isto é, o README)." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" +msgstr "Marcadores de ambiente" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -"A chave aceita uma string ou uma tabela. Se for uma string, então é um " -"caminho relativo ao ``pyproject.toml`` para um arquivo texto contendo a " -"descrição completa. As ferramentas DEVEM presumir que a codificação do " -"arquivo é UTF-8. Se o caminho do arquivo termina com um sufixo ``.md``, ou " -"sua versão em caixa alta, então as ferramentas DEVEM presumir que o tipo de " -"conteúdo é ``text/markdown``. Se o caminho do arquivo termina em ``.rst``, " -"então as ferramentas DEVEM presumir que o tipo de conteúdo é ``text/x-rst``. " -"Se uma ferramenta reconhece mais extensões do que esta PEP, elas podem " -"inferir o tipo de conteúdo para o usuário sem especificar esta chave como " -"``dynamic``. Para todos os sufixos não reconhecidos quando um tipo de " -"conteúdo não é fornecido, as ferramentas DEVEM levantar um erro." +"Os marcadores de ambiente permitem que uma especificação de dependência " +"forneça uma regra que descreva quando a dependência deve ser usada. Por " +"exemplo, considere um pacote que precisa de argparse. No Python 2.7, o " +"argparse está sempre presente. Em versões mais antigas Python, ele deve ser " +"instalado como uma dependência. Isso pode ser expresso como ::" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -"A chave ``readme`` também pode receber uma tabela. A chave ``file`` tem um " -"valor string que representa um caminho relativo a ``pyproject.toml`` para um " -"arquivo contendo a descrição completa. A chave ``text`` tem um valor de " -"string que é a descrição completa. Essas chaves são mutuamente exclusivas, " -"portanto, as ferramentas DEVEM levantar um erro se os metadados " -"especificarem ambas as chaves." +"Uma expressão de marcador é avaliada como True ou False. Quando for avaliado " +"como False, a especificação de dependência deve ser ignorada." -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -"Uma tabela especificada na chave ``readme`` também possui uma chave " -"``content-type`` que recebe uma string especificando o tipo de conteúdo da " -"descrição completa. Uma ferramenta DEVE levantar um erro se os metadados não " -"especificarem esse campo na tabela. Se os metadados não especificarem o " -"parâmetro ``charset``, será considerado UTF-8. As ferramentas PODEM oferecer " -"suporte a outras codificações, se assim o desejarem. As ferramentas PODEM " -"oferecer suporte a tipos de conteúdo alternativos que podem transformar em " -"um tipo de conteúdo conforme suportado pelos :ref:`metadados principais " -"`. Caso contrário, as ferramentas DEVEM levantar um erro para " -"tipos de conteúdo não suportados." +"A linguagem do marcador é inspirada no próprio Python, escolhido pela " +"capacidade de avaliá-lo com segurança sem executar código arbitrário que " +"pode se tornar uma vulnerabilidade de segurança. Os marcadores foram " +"padronizados pela primeira vez na :pep:`345`. Este documento corrige alguns " +"problemas que foram observados no projeto descrito em :pep:`426`." -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Requires-Python `" - -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." -msgstr "Os requisitos de versão do Python do projeto." - -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" -msgstr "Tipo TOML_: tabela" +"As comparações em expressões de marcador são tipadas pelo operador de " +"comparação. Os operadores que não estão em fazem o " +"mesmo que para strings no Python. Os operadores usam as regras " +"de comparação de versão da :ref:`especificação de especificadores de versão " +"` quando são definidas (ou seja, quando ambos os lados " +"têm um especificador de versão válido). Se não houver comportamento definido " +"desta especificação e o operador existir no Python, o operador voltará ao " +"comportamento do Python. Caso contrário, um erro deve ser levantado. Por " +"exemplo, o seguinte resultará em erros ::" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`License `" +"As constantes fornecidas pelo usuário são sempre codificadas como strings " +"com as aspas ``'`` ou ``\"``. Observe que os escapes de barra invertida não " +"são definidos, mas as implementações existentes os suportam. Eles não estão " +"incluídos nesta especificação porque adicionam complexidade e não há nenhuma " +"necessidade observável para eles hoje.Da mesma forma, não definimos suporte " +"a caracteres não-ASCII: espera-se que todas as variáveis de tempo de " +"execução às quais nos referimos sejam somente ASCII." -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -"A tabela pode ter uma de duas chaves. A chave ``file`` tem um valor de " -"string que é um caminho de arquivo relativo a ``pyproject.toml`` para o " -"arquivo que contém a licença do projeto. As ferramentas DEVEM presumir que a " -"codificação do arquivo é UTF-8. A chave ``text`` tem um valor de string que " -"é a licença do projeto. Essas chaves são mutuamente exclusivas, portanto, " -"uma ferramenta DEVE levantar um erro se os metadados especificarem ambas as " -"chaves." - -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" -msgstr "Tipo TOML_: Vetor de tabelas em linha com strings de chaves e valores" +"As variáveis na gramática do marcador, como \"os_name\", resolvem os valores " +"pesquisados no tempo de execução do Python. Com exceção de \"extra\" todos " +"os valores são definidos em todas as versões Python hoje -- é um erro na " +"implementação de marcadores se um valor não for definido." -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -"Campos correspondentes dos :ref:`metadados principais `: :ref:" -"`Author `, :ref:`Author-email `, :ref:`Maintainer ` e :ref:`Maintainer-" -"email `" +"Variáveis desconhecidas devem gerar um erro em vez de resultar em uma " +"comparação avaliada como True ou False." -#: ../source/specifications/declaring-project-metadata.rst:181 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -"As pessoas ou organizações consideradas \"autoras\" do projeto. O " -"significado exato está aberto à interpretação -- pode listar os autores " -"originais ou primários, mantenedores atuais ou proprietários do pacote." +"As variáveis cujo valor não pode ser calculado em uma determinada " +"implementação do Python devem ser avaliadas como ``0`` para versões e uma " +"string vazia para todas as outras variáveis." -#: ../source/specifications/declaring-project-metadata.rst:186 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -"A chave \"maintainers\" é semelhante a \"authors\" no sentido de que seu " -"significado exato está aberto à interpretação." +"A variável \"extra\" é especial. É usada pelo wheels para sinalizar quais " +"especificações se aplicam a um determinado extra no arquivo ``METADATA`` do " +"wheel, mas como o arquivo ``METADATA`` é baseado em uma versão de rascunho " +"da :pep:`426`, não há especificação atual para isso. Independentemente " +"disso, fora de um contexto em que esse tratamento especial esteja ocorrendo, " +"a variável \"extra\" deve resultar em um erro como todas as outras variáveis " +"desconhecidas." -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." -msgstr "" -"Estas chaves aceitam um vetor de tabelas com 2 chaves: ``name`` e ``email``. " -"Ambos os valores devem ser strings. O valor ``name`` DEVE ser um nome de e-" -"mail válido (ou seja, o que quer que possa ser colocado como um nome, antes " -"de um e-mail, em :rfc:`822`) e não conter vírgulas. O valor ``email`` DEVE " -"ser um endereço de email válido. Ambas as chaves são opcionais, mas ao menos " -"uma das chaves deve ser especificada na tabela." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" +msgstr "Marcador" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" -msgstr "" -"O uso dos dados para preencher :ref:`metadados principais ` " -"deve ser feito da seguinte forma:" +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" +msgstr "Equivalente no Python" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." -msgstr "" -"Se somente ``name`` for fornecido, o valor vai em :ref:`Author ` ou :ref:`Maintainer ` conforme " -"apropriado." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" +msgstr "Valores de amostra" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." -msgstr "" -"Se somente ``email`` é fornecido, o valor vai em :ref:`Author-email ` ou :ref:`Maintainer-email ` conforme apropriado." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" +msgstr "``os_name``" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." -msgstr "" -"Se ``email`` e ``name`` são fornecidos, o valor vai em :ref:`Author-email " -"` ou :ref:`Maintainer-email ` conforme apropriado, com o formado ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" +msgstr "``os.name``" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." -msgstr "Vários valores devem ser separados por vírgulas." +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" -msgstr "Tipo TOML_: vetor de strings" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "``sys_platform``" -#: ../source/specifications/declaring-project-metadata.rst:217 +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" +msgstr "``sys.platform``" + +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Keywords `" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (observe que \"linux\" é " +"do Python3 e \"linux2\" do Python2)" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." -msgstr "As palavras-chave do projeto." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" +msgstr "``platform_machine``" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" -msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Classifier `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" +msgstr "``platform.machine()``" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." -msgstr "Classificadores Trove que se aplicam ao projeto." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" +msgstr "``x86_64``" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" -msgstr "Tipo TOML_: tabela com chaves e valores de strings" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" -msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Project-URL `" +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" +msgstr "``platform.python_implementation()``" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." -msgstr "" -"Uma tabela de URLs onde a chave é o rótulo da URL e o valor é a URL em si." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" -msgstr "Pontos de entrada" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" +msgstr "``platform_release``" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" -msgstr "" -"Tipo TOML_: tabela (``[project.scripts]``, ``[project.gui-scripts]`` e " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" +msgstr "``platform.release()``" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" -msgstr ":ref:`Especificação de pontos de entrada `" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." -msgstr "" -"Existem três tabelas relacionadas aos pontos de entrada. A tabela ``[project." -"scripts]`` corresponde ao grupo ``console_scripts`` na :ref:`especificação " -"de pontos de entrada `. A chave da tabela é o nome do ponto de " -"entrada e o valor é a referência do objeto." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" +msgstr "``platform_system``" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." -msgstr "" -"A tabela ``[project.gui-scripts]`` corresponde ao grupo ``gui_scripts`` na :" -"ref:`especificação de pontos de entrada `. Seu formato é o " -"mesmo que ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" +msgstr "``platform.system()``" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" -#: ../source/specifications/declaring-project-metadata.rst:261 +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "``platform_version``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" +msgstr "``platform.version()``" + +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -"A tabela ``[project.entry-points]`` é uma coleção de tabelas. O nome de cada " -"subtabela é um grupo de pontos de entrada. A chave e a semântica do valor " -"são iguais a ``[project.scripts]``. Os usuários NÃO DEVEM criar subtabelas " -"aninhadas, mas sim manter os grupos de pontos de entrada em apenas um nível " -"de profundidade." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" +msgstr "``platform.python_version()``" + +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" +msgstr "``sys.implementation.name``" -#: ../source/specifications/declaring-project-metadata.rst:267 +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" +msgstr "veja a definição abaixo" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +"An error except when defined by the context interpreting the specification." msgstr "" -"Backends de construção DEVEM levantar um erro se os metadados definem uma " -"tabela ``[project.entry-points.console_scripts]`` ou ``[project.entry-points." -"gui_scripts]``, pois elas seriam ambíguas perante ``[project.scripts]`` e " -"``[project.gui-scripts]``, respectivamente." +"Um erro, exceto quando definido pelo contexto que interpreta a especificação." + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" +msgstr "``test``" -#: ../source/specifications/declaring-project-metadata.rst:277 +#: ../source/specifications/dependency-specifiers.rst:277 +#, fuzzy +#| msgid "" +#| "The ``implementation_version`` marker variable is derived from ``sys." +#| "implementation.version``::" msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -"Tipo TOML_: Vetor de strings da :pep:`508` (``dependencies``) e uma tabela " -"com valores de vetores de strings da :pep:`508` (``optional-dependencies``)" +"A variável do marcador ``implementation_version`` é derivada de ``sys." +"implementation.version``::" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Requires-Dist ` e :ref:`Provides-Extra `" +"Esta seção de marcadores de ambiente, inicialmente definida na :pep:`508`, " +"substitui a seção de marcadores de ambiente na :pep:`345`." -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." -msgstr "As dependências (opcionais) do projeto." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" +msgstr "Gramática completa" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." -msgstr "" -"Para ``dependencies``, é uma chave cujo valor é um array de strings. Cada " -"string representa uma dependência do projeto e DEVE ser formatada como uma " -"string válida :pep:`508`. Cada string mapeia diretamente para um :ref:" -"`Requires-Dist `." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" +msgstr "A gramática completa do persley ::" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +#: ../source/specifications/dependency-specifiers.rst:407 +#, fuzzy +#| msgid "A test program - if the grammar is in a string ``grammar``::" +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -"Para ``optional-dependencies``, é uma tabela onde cada chave especifica um " -"extra e cujo valor é um vetor de strings. As strings dos vetores devem ser " -"strings válidas da :pep:`508`. As chaves DEVEM ser valores válidos para :ref:" -"`Provides-Extra `. Cada valor no vetor torna-" -"se assim uma entrada correspondente de :ref:`Requer-Dist ` para os metadados correspondentes de :ref:`Provides-Extra " -"`." +"Um programa de teste -- se a gramática estiver em uma string ``grammar``::" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" -msgstr "Tipo TOML_: vetor de string" +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" +msgstr "Resumo das alterações à PEP 508" -#: ../source/specifications/declaring-project-metadata.rst:308 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -"Campo correspondente dos :ref:`metadados principais `: :ref:" -"`Dynamic `" +"As seguintes alterações foram feitas com base no feedback após sua " +"implementação inicial:" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -"Especifica quais chaves listadas por esta PEP foram intencionalmente não " -"especificadas para que outra ferramenta possa/vai fornecer tais metadados " -"dinamicamente. Isso delineia claramente quais metadados são propositalmente " -"não especificados e espera-se que permaneçam não especificados em comparação " -"a serem fornecidos por meio de ferramentas posteriormente." +"A definição de ``python_version`` foi alterada de ``platform.python_version()" +"[:3]`` para ``'.'.join(platform.python_version_tuple()[:2])``, para acomodar " +"potenciais futuras versões do Python com versões principais e secundárias de " +"2 dígitos (por exemplo, 3.10). [#future_versions]_" -#: ../source/specifications/declaring-project-metadata.rst:317 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -"Um backend de construção DEVE respeitar metadados especificados " -"estaticamente (o que significa que os metadados não listam a chave em " -"``dynamic``)." +"pip, o instalador recomendado para pacotes Python (http://pip.readthedocs." +"org/en/stable/)" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -"Um backend de construção DEVE gerar um erro se os metadados especificarem " -"``name`` em ``dynamic``." +"A biblioteca de PEG do parsley. (https://pypi.python.org/pypi/parsley/)" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -"Se a especificação de :ref:`metadados principais ` lista um " -"campo como \"Required\", então os metadados DEVEM especificar a chave " -"estaticamente ou listá-la em ``dynamic`` (backends de construção DEVEM gerar " -"um erro, caso contrário , ou seja, não deve ser possível que uma chave " -"obrigatória não seja listada de alguma forma na tabela ``[project]``)." +"Versões futuras do Python podem ser problemáticas com a definição da " +"variável do marcador de ambiente ``python_version`` (https://github.com/" +"python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "Gravando a Origem da URL Direta de distribuições instaladas" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/direct-url.rst:8 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -"Se a especificação de :ref:`metadados principais ` listar um " -"campo como \"Optional\", os metadados PODEM listá-lo em ``dynamic`` se a " -"expectativa for um backend de construção fornecerá os dados para a chave " -"mais tarde." +"Este documento especifica um arquivo :file:`direct_url.json` no diretório " +"``*.dist-info`` de uma distribuição instalada, para registrar a origem da " +"URL direta da distribuição. A estrutura geral e uso de diretórios ``*.dist-" +"info`` é descrita em :ref:`recording-installed-packages`." -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/direct-url.rst:17 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -"Os backends de construção DEVEM levantar um erro se os metadados " -"especificarem uma chave estaticamente, além de serem listados em ``dynamic``." +"O arquivo :file:`direct_url.json` DEVE ser criado no diretório :file:`*.dist-" +"info` pelos instaladores ao instalar uma distribuição a partir de um " +"requisito especificando uma referência de URL direta (incluindo uma URL de " +"VCS)." -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -"Se os metadados não listam uma chave em ``dynamic``, então um backend de " -"construção NÃO PODE preencher os metadados necessários em nome do usuário " -"(ou seja, ``dynamic`` é a única maneira de permitir que uma ferramenta " -"preencha metadados e o usuário deve optar pelo preenchimento)." +"Este arquivo NÃO DEVE ser criado ao instalar uma distribuição de outro tipo " +"de requisito (ou seja, nome mais especificador de versão)." -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/direct-url.rst:24 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -"Os backends de construção DEVEM levantar um erro se os metadados " -"especificarem uma chave em ``dynamic``, mas o backend de construção não foi " -"capaz de determinar os dados para ele (omitir os dados, se determinado como " -"o valor exato, é aceitável) ." - -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" -msgstr "Especificadores de dependência" +"Este arquivo JSON DEVE ser codificado em UTF-8, compatível com :rfc:`8259`, " +"serialização da :doc:`direct-url-data-structure`." -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:29 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -"Este documento descreve o formato dos especificadores de dependência " -"conforme originalmente especificado na :pep:`508`." +"Quando a URL solicitada tem o esquema file:// e aponta para um diretório " +"local que contém um checkout VCS, os instaladores NÃO DEVEM tentar inferir " +"nenhuma informação VCS e, portanto, NÃO DEVEM emitir nenhuma informação " +"relacionada ao VCS (como ``vcs_info``) in :file:`direct_url.json`." -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:36 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -"O trabalho de uma dependência é permitir que ferramentas como pip [#pip]_ " -"encontrem o pacote certo para instalar. Às vezes, isso é muito vago -- " -"apenas especificando um nome -- e, às vezes, muito específico -- referindo-" -"se a um arquivo específico a ser instalado. Às vezes, as dependências são " -"relevantes apenas em uma plataforma, ou apenas algumas versões são " -"aceitáveis, então a linguagem permite descrever todos esses casos." +"Como regra geral, os instaladores devem, tanto quanto possível, preservar as " +"informações fornecidas na URL solicitada ao gerar :file:`direct_url.json`. " +"Por exemplo, as variáveis de ambiente usuário:senha devem ser preservadas e " +"``required_revision`` deve refletir a revisão que foi fornecida na URL " +"solicitada o mais fielmente possível. No entanto, essas informações são " +"*enriquecidas* com dados mais precisos, como ``commit_id``." + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "Exemplo de comandos pip e seus efeitos em direct_url.json" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "Comandos que geram um ``direct_url.json``:" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:49 #, fuzzy -#| msgid "" -#| "The language defined is a compact line based format which is already in " -#| "widespread use in pip requirements files, though we do not specify the " -#| "command line option handling that those files permit. There is one caveat " -#| "- the URL reference form, specified in :pep:`440` is not actually " -#| "implemented in pip, but since :pep:`440` is accepted, we use that format " -#| "rather than pip's current native format." +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "pip install https://example.com/app-1.0.tgz" + +#: ../source/specifications/direct-url.rst:50 +#, fuzzy +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "pip install https://example.com/app-1.0.whl" + +#: ../source/specifications/direct-url.rst:51 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -"A linguagem definida é um formato compacto baseado em linha que já está em " -"uso generalizado em arquivos de requisitos pip, embora não especifiquemos a " -"manipulação de opção de linha de comando que esses arquivos permitem. Há uma " -"ressalva: o formulário de referência de URL, especificado em :pep:`440`, não " -"é realmente implementado em pip, mas como :pep:`440` é aceito, usamos esse " -"formato em vez do formato nativo atual de pip." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:52 +#, fuzzy +msgid "``pip install ./app``" +msgstr "pip install ./app" + +#: ../source/specifications/direct-url.rst:53 +#, fuzzy +msgid "``pip install file:///home/user/app``" +msgstr "pip install file:///home/user/app" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -"Todos os recursos do idioma mostrados com uma pesquisa baseada em nome ::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (caso em que, ``url`` será o diretório local para " +"o qual o repositório git foi clonado e ``dir_info`` estará presente com " +"``\"editable\": true`` e nenhum ``vcs_info`` será definido)" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" -msgstr "Uma pesquisa baseada em URL mínima ::" +#: ../source/specifications/direct-url.rst:58 +#, fuzzy +msgid "``pip install -e ./app``" +msgstr "pip install -e ./app" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" -msgstr "Conceitos" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "Comandos que *não* geram um ``direct_url.json``" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "pip install app" + +#: ../source/specifications/direct-url.rst:63 +#, fuzzy +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "pip install app --no-index --find-links https://example.com/" + +#: ../source/specifications/direct-url.rst:68 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -"Uma especificação de dependência sempre especifica um nome de distribuição. " -"Pode incluir extras, que expandem as dependências da distribuição nomeada " -"para habilitar recursos opcionais. A versão instalada pode ser controlada " -"usando limites de versão ou fornecendo a URL para um artefato específico " -"para instalação. Finalmente, a dependência pode ser condicionada usando " -"marcadores de ambiente." +"Março de 2020: o arquivo de metadados ``direct_url.json`` foi originalmente " +"especificado na :pep:`610` e está formalmente documentado aqui." -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" -msgstr "Gramática" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "Estrutura de dados de URL direta" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -"Primeiro, abordamos brevemente a gramática e, posteriormente, detalhamos a " -"semântica de cada seção." +"Este documento especifica uma estrutura de dados abstrata serializável em " +"JSON que pode representar URLs para projetos python e artefatos de " +"distribuição, como árvores de fonte VCS, árvores de fonte local, " +"distribuições fonte e wheels." -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -"Uma especificação de distribuição é escrita em texto ASCII. Usamos uma " -"gramática de parsley [#parsley]_ para fornecer uma gramática precisa. Espera-" -"se que a especificação seja incorporada a um sistema maior que ofereça " -"enquadramento, como comentários, suporte a várias linhas por meio de " -"continuações ou outros recursos semelhantes." +"A representação dos componentes desta estrutura de dados como uma URL :rfc:" +"`1738` não é especificada formalmente no momento da escrita. Uma " +"representação comum é o formato de URL do pip. Outros exemplos são " +"fornecidos na :ref:`especificação de especificadores de versão `." -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -"A gramática completa, incluindo anotações para construir uma árvore de " -"análise útil, está incluída no final deste documento." +"A estrutura de dados da URL direta DEVE ser um dicionário serializável para " +"JSON de acordo com :rfc:`8259`." -#: ../source/specifications/dependency-specifiers.rst:60 -#, fuzzy -#| msgid "" -#| "Versions may be specified according to the :pep:`440` rules. (Note: URI " -#| "is defined in :rfc:`std-66 <3986>`)::" +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -"As versões podem ser especificadas de acordo com as regras da :pep:`440`. " -"(Nota: URI é definido em :rfc:`std-66 <3986>`)::" +"DEVE conter pelo menos dois campos. O primeiro é ``url``, com tipo " +"``string``. Dependendo de qual ``url`` se refere, o segundo campo DEVE ser " +"um de ``vcs_info`` (se ``url`` é uma referência de VCS), ``archive_info`` " +"(se ``url`` é um pacote de código-fonte ou um wheel) ou ``dir_info`` (se " +"``url`` é um diretório local). Estes campos informacionais têm um " +"subdicionário (possivelmente vazio) como valor, com as chaves possíveis " +"definidas abaixo." -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -"Os marcadores de ambiente permitem que uma especificação só tenha efeito em " -"alguns ambientes ::" +"Quando persistido, ``url`` DEVE ser podado a fim de retirar qualquer " +"informação sensível de autenticação, por razões de segurança." -#: ../source/specifications/dependency-specifiers.rst:100 +#: ../source/specifications/direct-url-data-structure.rst:34 +#, fuzzy +#| msgid "" +#| "The user:password section of the URL MAY however be composed of " +#| "environment variables, matching the following regular expression::" msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -"Componentes opcionais de uma distribuição podem ser especificados usando o " -"campo extras::" - -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." -msgstr "Restrições de nomes para extras são definidas na :pep:`685`." - -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" -msgstr "Fornecendo uma regra para requisitos baseados em nome ::" - -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" -msgstr "E uma regra para especificações de referência direta ::" - -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" -msgstr "Levando à regra unificada que pode especificar uma dependência.::" - -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" -msgstr "Espaço em branco" +"A seção usuário:senha da URL PODE, entretanto, ser composta de variáveis de " +"ambiente, correspondendo à seguinte expressão regular::" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -"O espaço em branco sem quebra de linha é principalmente opcional, sem " -"significado semântico. A única exceção é detectar o fim de um requisito de " -"URL." +"Além disso, a seção usuário:senha da URL PODE ser uma string bem conhecida e " +"não sensível à segurança. Um exemplo típico é ``git`` no caso de uma URL " +"como ``ssh://git@gitlab.com/user/repo``." -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" -msgstr "Nomes" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" +msgstr "URLs de VCS" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -"Nomes de distribuição Python são atualmente definidos na :pep:`345`. Os " -"nomes atuam como o identificador primário para distribuições. Eles estão " -"presentes em todas as especificações de dependência e são suficientes para " -"serem uma especificação por conta própria. No entanto, PyPI impõe restrições " -"estritas aos nomes: eles devem corresponder a uma regex que não diferencie " -"maiúsculas de minúsculas ou não serão aceitos. Assim, neste documento, " -"limitamos os valores aceitáveis para identificadores a essa regex. Uma " -"redefinição completa do nome pode ocorrer em um futuro PEP de metadados. A " -"regex (executada com re.IGNORECASE) é ::" - -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" -msgstr "Extras" +"Quando a ``url`` faz referência a um repositório VCS, a chave ``vcs_info`` " +"DEVE estar presente como um dicionário com as seguintes chaves:" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -"Um extra é uma parte opcional de uma distribuição. As distribuições podem " -"especificar quantos extras desejarem, e cada extra resulta na declaração de " -"dependências adicionais da distribuição **quando** o extra é usado em uma " -"especificação de dependência. Por exemplo ::" +"Uma chave ``vcs`` (tipo ``string``) DEVE estar presente, contendo o nome do " +"VCS (ou seja, um de ``git``, ``hg``, ``bzr``, ``svn``). Outros VCS DEVERIAM " +"ser registrados escrevendo uma PEP para alterar esta especificação. O valor " +"``url`` DEVE ser compatível com o VCS correspondente, para que um instalador " +"possa entregá-lo sem transformação em um comando de checkout/download do VCS." -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -"União de extras nas dependências que definem com as dependências da " -"distribuição à qual estão anexados. O exemplo acima resultaria na instalação " -"de solicitações e nas próprias dependências das solicitações, além de " -"quaisquer dependências listadas no extra de \"security\" das solicitações." +"Uma chave ``required_revision`` (tipo ``string``) PODE estar presente " +"nomeando um branch/tag/ref/commit/revisão/etc (em um formato compatível com " +"o VCS)." -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." -msgstr "Se vários extras forem listados, todas as dependências serão unidas." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" +"Uma chave ``commit_id`` (tipo ``string``) DEVE estar presente, contendo o " +"número exato de commit/revisão que foi/será instalado. Se o VCS oferecer " +"suporte a identificadores de revisão baseados em hash de commit, tal hash de " +"commit DEVE ser usado como ``commit_id`` para referenciar a versão imutável " +"do código-fonte." -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" -msgstr "Versões" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" +msgstr "URLs de arquivos" -#: ../source/specifications/dependency-specifiers.rst:163 -#, fuzzy -#| msgid "" -#| "See :pep:`440` for more detail on both version numbers and version " -#| "comparisons. Version specifications limit the versions of a distribution " -#| "that can be used. They only apply to distributions looked up by name, " -#| "rather than via a URL. Version comparison are also used in the markers " -#| "feature. The optional brackets around a version are present for " -#| "compatibility with :pep:`345` but should not be generated, only accepted." +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -"Consulte :pep:`440` para obter mais detalhes sobre números de versão e " -"comparações de versão. As especificações de versão limitam as versões de uma " -"distribuição que podem ser usadas. Eles se aplicam apenas a distribuições " -"pesquisadas pelo nome, e não por meio de um URL. A comparação de versões " -"também é usada no recurso de marcadores. Os colchetes opcionais em torno de " -"uma versão estão presentes para compatibilidade com :pep:`345`, mas não " -"devem ser gerados, apenas aceitos." - -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" -msgstr "Marcadores de ambiente" +"Quando ``url`` se refere a um arquivo fonte ou wheel, a chave " +"``archive_info`` DEVE estar presente como um dicionário com as seguintes " +"chaves:" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -"Os marcadores de ambiente permitem que uma especificação de dependência " -"forneça uma regra que descreva quando a dependência deve ser usada. Por " -"exemplo, considere um pacote que precisa de argparse. No Python 2.7, o " -"argparse está sempre presente. Em versões mais antigas Python, ele deve ser " -"instalado como uma dependência. Isso pode ser expresso como ::" +"Uma chave ``hashes`` DEVE estar presente como um dicionário mapeando um nome " +"de hash para um resumo de arquivo codificado em hex." -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -"Uma expressão de marcador é avaliada como True ou False. Quando for avaliado " -"como False, a especificação de dependência deve ser ignorada." +"Vários hashes podem ser incluídos e cabe ao consumidor decidir o que fazer " +"com vários hashes (pode validar todos eles ou um subconjunto deles, ou nada)." + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" +"Esses nomes de hash DEVEM sempre ser normalizados para letras minúsculas." -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -"A linguagem do marcador é inspirada no próprio Python, escolhido pela " -"capacidade de avaliá-lo com segurança sem executar código arbitrário que " -"pode se tornar uma vulnerabilidade de segurança. Os marcadores foram " -"padronizados pela primeira vez na :pep:`345`. Este documento corrige alguns " -"problemas que foram observados no projeto descrito em :pep:`426`." +"Qualquer algoritmo de hash disponível via ``hashlib`` (especificamente " +"qualquer um que possa ser passado para ``hashlib.new()`` e não requeira " +"parâmetros adicionais) pode ser usado como uma chave para o dicionário de " +"hashes. Pelo menos um algoritmo seguro de ``hashlib.algorithms_guaranteed`` " +"DEVE sempre ser incluído. No momento da escrita, ``sha256`` especificamente " +"é recomendado." + +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"Uma chave descontinuada ``hash`` (tipo ``string``) PODE estar presente para " +"fins de compatibilidade com versões anteriores, com valor ``=``." -#: ../source/specifications/dependency-specifiers.rst:189 -#, fuzzy -#| msgid "" -#| "Comparisons in marker expressions are typed by the comparison operator. " -#| "The operators that are not in perform the same " -#| "as they do for strings in Python. The operators use the :" -#| "pep:`440` version comparison rules when those are defined (that is when " -#| "both sides have a valid version specifier). If there is no defined :pep:" -#| "`440` behaviour and the operator exists in Python, then the operator " -#| "falls back to the Python behaviour. Otherwise an error should be raised. " -#| "e.g. the following will result in errors::" +#: ../source/specifications/direct-url-data-structure.rst:91 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -"As comparações em expressões de marcador são tipadas pelo operador de " -"comparação. Os operadores que não estão em " -"executam o mesmo que para strings no Python. Os operadores " -"usam as regras de comparação de versão :pep:`440` quando são definidas (ou " -"seja, quando ambos os lados têm um especificador de versão válido). Se não " -"houver comportamento da :pep:`440` definido e o operador existir no Python, " -"o operador voltará ao comportamento do Python. Caso contrário, um erro deve " -"ser levantado. Por exemplo, o seguinte resultará em erros ::" +"Os produtores da estrutura de dados DEVEM emitir a chave ``hashes`` se um ou " +"vários hashes estiverem disponíveis. Os produtores DEVEM continuar a emitir " +"a chave ``hash`` em contextos onde o faziam antes, de modo a manter a " +"compatibilidade com versões anteriores para clientes existentes." -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:95 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -"As constantes fornecidas pelo usuário são sempre codificadas como strings " -"com as aspas ``'`` ou ``\"``. Observe que os escapes de barra invertida não " -"são definidos, mas as implementações existentes os suportam. Eles não estão " -"incluídos nesta especificação porque adicionam complexidade e não há nenhuma " -"necessidade observável para eles hoje.Da mesma forma, não definimos suporte " -"a caracteres não-ASCII: espera-se que todas as variáveis de tempo de " -"execução às quais nos referimos sejam somente ASCII." +"Quando as chaves ``hash`` e ``hashes`` estão presentes, o hash representado " +"na chave ``hash`` DEVE também estar presente no dicionário ``hashes``, para " +"que os consumidores possam considerar a chave ``hashes`` apenas se estiver " +"presente, e voltar para ``hash`` caso contrário." + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" +msgstr "Diretórios locais" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:102 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -"As variáveis na gramática do marcador, como \"os_name\", resolvem os valores " -"pesquisados no tempo de execução do Python. Com exceção de \"extra\" todos " -"os valores são definidos em todas as versões Python hoje -- é um erro na " -"implementação de marcadores se um valor não for definido." +"Quando ``url`` se refere a um diretório local, a chave ``dir_info`` DEVE " +"estar presente como um dicionário com a seguinte chave:" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -"Variáveis desconhecidas devem gerar um erro em vez de resultar em uma " -"comparação avaliada como True ou False." +"``editable`` (tipo: ``boolean``): ``true`` se a distribuição foi/será " +"instalada em modo editável, ``false`` caso contrário. Se ausente, é usado o " +"padrão ``false``." -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -"As variáveis cujo valor não pode ser calculado em uma determinada " -"implementação do Python devem ser avaliadas como ``0`` para versões e uma " -"string vazia para todas as outras variáveis." +"Quando ``url`` se refere a um diretório local, ele DEVE ter o esquema " +"``file`` e ser compatível com :rfc:`8089` Em particular, o componente do " +"caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao " +"tornar os caminhos relativos absolutos." + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" +msgstr "Projetos em subdiretórios" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -"A variável \"extra\" é especial. É usada pelo wheels para sinalizar quais " -"especificações se aplicam a um determinado extra no arquivo ``METADATA`` do " -"wheel, mas como o arquivo ``METADATA`` é baseado em uma versão de rascunho " -"da :pep:`426`, não há especificação atual para isso. Independentemente " -"disso, fora de um contexto em que esse tratamento especial esteja ocorrendo, " -"a variável \"extra\" deve resultar em um erro como todas as outras variáveis " -"desconhecidas." +"Um campo ``subdirectory`` de nível superior PODE estar presente contendo um " +"caminho de diretório, relativo à raiz do repositório VCS, arquivo fonte ou " +"diretório local, para especificar onde ``pyproject.toml`` ou ``setup.py`` " +"está localizado." -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" -msgstr "Marcador" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" +msgstr "VCS registrados" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" -msgstr "Equivalente no Python" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"Esta seção lista os VCS registrados; expandidos, informações específicas do " +"VCS sobre como usar ``vcs``, ``required_revision`` e outros campos de " +"``vcs_info``; e, em alguns casos, campos adicionais específicos de VCS. As " +"ferramentas PODEM oferecer suporte a outros VCS, embora seja RECOMENDADO " +"registrá-las escrevendo uma PEP para alterar esta especificação. O campo " +"``vcs`` DEVERIA ser o nome do comando (em letras minúsculas). Os campos " +"adicionais que seriam necessários para oferecer suporte a esse VCS DEVERIAM " +"ser prefixados com o nome do comando VCS." -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" -msgstr "Valores de amostra" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" +msgstr "Git" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" -msgstr "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" +msgstr "Site" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" -msgstr "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" -msgstr "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" +msgstr "Comando vcs" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" -msgstr "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" +msgstr "git" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" -msgstr "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" +msgstr "Campo ``vcs``" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" +msgstr "Campo ``requested_revision``" + +#: ../source/specifications/direct-url-data-structure.rst:145 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (observe que \"linux\" é " -"do Python3 e \"linux2\" do Python2)" - -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" -msgstr "``platform_machine``" +"Um nome de tag, nome de branch, ref Git, hash de commit, hash de commit " +"encurtado ou outra coisa relacionada a commit." -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" -msgstr "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" +msgstr "Campo ``commit_id``" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" -msgstr "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "Um hash de confirmação (40 caracteres hexadecimais sha1)." -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" -msgstr "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"As ferramentas podem usar os comandos ``git show-ref`` e ``git symbolic-" +"ref`` para determinar se o ``required_revision`` corresponde a um ref Git. " +"Por sua vez, um ref começando com ``refs/tags/`` corresponde a uma tag, e um " +"ref começando com ``refs/remotes/origin/`` após a clonagem corresponde a um " +"branch." -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" -msgstr "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" +msgstr "Mercurial" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" -msgstr "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" -msgstr "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "hg" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" -msgstr "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" +"Um nome de tag, nome de branch, ID de changeset, ID de changeset abreviado." -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" -msgstr "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "Um ID de changeset (40 caracteres hexadecimais)." -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" -msgstr "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" +msgstr "Bazaar" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" -msgstr "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +#, fuzzy +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" -msgstr "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" +msgstr "bzr" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" -msgstr "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." +msgstr "Um nome de tag, nome de branch, id de revisão." -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" -msgstr "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." +msgstr "Um id de revisão." -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" - -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" -msgstr "``python_version``" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" -msgstr "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" -msgstr "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" +msgstr "svn" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" -msgstr "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." +msgstr "" +"``requested_revision`` deve ser compatível com a opção ``--revision`` do " +"``svn checkout``. No Subversion, branch ou tag é parte de ``url``." -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" -msgstr "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:212 +msgid "" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." +msgstr "" +"Visto que o Subversion não oferece suporte a identificadores globalmente " +"únicos, este campo é o número da revisão do Subversion no repositório " +"correspondente." -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" -msgstr "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" +msgstr "Arquivo fonte:" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" -msgstr "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" +msgstr "URL Git com tag e hash de commit:" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" -msgstr "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" +msgstr "Diretório local:" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" -msgstr "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" +msgstr "Diretório local em modo editável:" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" -msgstr "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." +msgstr "" +"Março de 2020: esta estrutura de dados foi originalmente especificada como " +"parte do arquivo de metadados ``direct_url.json`` em :pep:`610` e está " +"formalmente documentada aqui." -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" -msgstr "veja a definição abaixo" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." +msgstr "" +"Janeiro de 2023: Adicionada a chave ``archive_info.hashes`` (`discussão " +"`__)." -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" -msgstr "``extra``" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "Especificação de pontos de entrada" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/entry-points.rst:7 msgid "" -"An error except when defined by the context interpreting the specification." +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -"Um erro, exceto quando definido pelo contexto que interpreta a especificação." - -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" -msgstr "``test``" +"*Pontos de entrada* são um mecanismo para uma distribuição instalada " +"anunciar componentes que ela fornece para serem descobertos e usados por " +"outro código. Por exemplo:" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -"A variável do marcador ``implementation_version`` é derivada de ``sys." -"implementation.version``::" +"As distribuições podem especificar pontos de entrada ``console_scripts``, " +"cada um referindo-se a uma função. Quando *pip* (ou outro instalador " +"compatível com console_scripts) instala a distribuição, ele cria um wrapper " +"de linha de comando para cada ponto de entrada." -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/entry-points.rst:14 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -"Esta seção de marcadores de ambiente, inicialmente definida na :pep:`508`, " -"substitui a seção de marcadores de ambiente na :pep:`345`." +"As aplicações podem usar pontos de entrada para carregar plug-ins; por " +"exemplo, Pygments (uma ferramenta de realce de sintaxe) pode usar lexers e " +"estilos adicionais de pacotes instalados separadamente. Para mais " +"informações, consulte :doc:`/guides/creating-and-discovering-plugins`." -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" -msgstr "Gramática completa" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." +msgstr "" +"O formato de arquivo de ponto de entrada foi originalmente desenvolvido para " +"permitir que pacotes construídos com setuptools forneçam metadados de ponto " +"de integração que seriam lidos em tempo de execução com ``importlib." +"metadata``. Ele agora é definido como uma especificação de " +"interoperabilidade PyPA a fim de permitir que outras ferramentas de " +"construção além do setuptools publiquem metadados de ponto de entrada " +"compatíveis com ``importlib.metadata`` e bibliotecas de tempo de execução " +"diferentes de ``importlib.metadata`` para ler portavelmente publicado " +"metadados de ponto de entrada (potencialmente com diferentes estratégias de " +"cache e resolução de conflitos)." -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" -msgstr "A gramática completa do persley ::" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Modelo de dados" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -"Um programa de teste -- se a gramática estiver em uma string ``grammar``::" +"Conceitualmente, um ponto de entrada é definido por três propriedades " +"necessárias:" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" -msgstr "Resumo das alterações à PEP 508" +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." +msgstr "" +"O **grupo** ao qual um ponto de entrada pertence indica que tipo de objeto " +"ele fornece. Por exemplo, o grupo ``console_scripts`` é para pontos de " +"entrada referentes a funções que podem ser usadas como um comando, enquanto " +"``pygments.styles`` é o grupo para classes que definem estilos de pigmentos. " +"O consumidor normalmente define a interface esperada. Para evitar conflitos, " +"os consumidores que definem um novo grupo devem usar nomes começando com um " +"nome PyPI pertencente ao projeto do consumidor, seguido por ``.``. Os nomes " +"dos grupos devem ser um ou mais grupos de letras, números e sublinhados, " +"separados por pontos (regex ``^\\w+(\\.\\w+)*$``)." -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -"As seguintes alterações foram feitas com base no feedback após sua " -"implementação inicial:" +"O **nome** identifica este ponto de entrada em seu grupo. O significado " +"preciso disso depende do cliente. Para scripts de console, o nome do ponto " +"de entrada é o comando que será usado para iniciá-lo. Em uma distribuição, " +"os nomes dos pontos de entrada devem ser exclusivos. Se distribuições " +"diferentes fornecerem o mesmo nome, o consumidor decide como lidar com tais " +"conflitos. O nome pode conter quaisquer caracteres, exceto ``=``, mas não " +"pode começar ou terminar com nenhum caractere de espaço em branco, ou " +"começar com ``[``. Para novos pontos de entrada, é recomendado usar apenas " +"letras, números, sublinhados, pontos e travessões (regex ``[\\w.-]+``)." -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:51 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -"A definição de ``python_version`` foi alterada de ``platform.python_version()" -"[:3]`` para ``'.'.join(platform.python_version_tuple()[:2])``, para acomodar " -"potenciais futuras versões do Python com versões principais e secundárias de " -"2 dígitos (por exemplo, 3.10). [#future_versions]_" +"A **referência de objeto** aponta para um objeto Python. Ele está no formato " +"``importable.module`` ou ``importable.module:object.attr``. Cada uma das " +"partes delimitadas por pontos e dois pontos é um identificador válido " +"Python. Destina-se a ser consultado assim::" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:64 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -"pip, o instalador recomendado para pacotes Python (http://pip.readthedocs." -"org/en/stable/)" +"Algumas ferramentas chamam esse tipo de referência de objeto por si só de " +"\"ponto de entrada\", por falta de um termo melhor, especialmente quando " +"aponta para uma função para iniciar um programa." -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -"A biblioteca de PEG do parsley. (https://pypi.python.org/pypi/parsley/)" +"Há também uma propriedade opcional: os **extras** são um conjunto de strings " +"que identifica recursos opcionais da distribuição que fornece o ponto de " +"entrada. Se forem especificados, o ponto de entrada requer as dependências " +"desses 'extras'. Veja o campo de metadados :ref:`metadata_provides_extra`." -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:73 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -"Versões futuras do Python podem ser problemáticas com a definição da " -"variável do marcador de ambiente ``python_version`` (https://github.com/" -"python/peps/issues/560)" +"Usar extras para um ponto de entrada não é mais recomendado. Os consumidores " +"devem oferecer suporte para analisá-los em distribuições existentes, mas " +"podem então ignorá-los. Novas ferramentas de publicação não precisam " +"suportar especificações extras. A funcionalidade de manipulação de extras " +"estava ligada ao modelo do setuptools de gerenciamento de pacotes \"egg\", " +"mas as ferramentas mais recentes, como pip e virtualenv, usam um modelo " +"diferente." -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" -msgstr "Gravando a Origem da URL Direta de distribuições instaladas" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Formato de arquivo" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:82 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -"Este documento especifica um arquivo :file:`direct_url.json` no diretório " -"``*.dist-info`` de uma distribuição instalada, para registrar a origem da " -"URL direta da distribuição. A estrutura geral e uso de diretórios ``*.dist-" -"info`` é descrita em :ref:`recording-installed-packages`." +"Os pontos de entrada são definidos em um arquivo chamado :file:`entry_points." +"txt` no diretório :file:`*.dist-info` da distribuição. Este é o diretório " +"descrito em :ref:`recording-installed-packages` para distribuições " +"instaladas e em :ref:`binary-distribution-format` para wheels. O arquivo usa " +"a codificação de caracteres UTF-8." -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:88 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -"O arquivo :file:`direct_url.json` DEVE ser criado no diretório :file:`*.dist-" -"info` pelos instaladores ao instalar uma distribuição a partir de um " -"requisito especificando uma referência de URL direta (incluindo uma URL de " -"VCS)." +"O conteúdo do arquivo está no formato INI, conforme lido pelo módulo :mod:" +"`configparser` do Python. No entanto, o configparser trata os nomes como não " +"diferenciando maiúsculas de minúsculas por padrão, enquanto os nomes de " +"pontos de entrada diferenciam maiúsculas de minúsculas. Um analisador de " +"configuração com distinção entre maiúsculas e minúsculas pode ser feito " +"assim::" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:98 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -"Este arquivo NÃO DEVE ser criado ao instalar uma distribuição de outro tipo " -"de requisito (ou seja, nome mais especificador de versão)." +"O arquivo de pontos de entrada deve sempre usar ``=`` para delimitar nomes " +"de valores (enquanto o configparser também permite o uso de ``:``)." -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:101 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -"Este arquivo JSON DEVE ser codificado em UTF-8, compatível com :rfc:`8259`, " -"serialização da :doc:`direct-url-data-structure`." +"As seções do arquivo de configuração representam grupos de pontos de " +"entrada, os nomes são nomes e os valores codificam a referência do objeto e " +"os extras opcionais. Se extras forem usados, eles serão uma lista separada " +"por vírgulas entre colchetes." -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:105 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -"Quando a URL solicitada tem o esquema file:// e aponta para um diretório " -"local que contém um checkout VCS, os instaladores NÃO DEVEM tentar inferir " -"nenhuma informação VCS e, portanto, NÃO DEVEM emitir nenhuma informação " -"relacionada ao VCS (como ``vcs_info``) in :file:`direct_url.json`." +"Dentro de um valor, os leitores devem aceitar e ignorar os espaços " +"(incluindo vários espaços consecutivos) antes ou depois dos dois pontos, " +"entre a referência do objeto e o colchete esquerdo, entre os nomes extras e " +"os colchetes e dois pontos que os delimitam, e depois do quadrado direito " +"suporte. A sintaxe para extras é formalmente especificada como parte da :pep:" +"`508` (como ``extras``) e restrições em valores especificados na :pep:`685`. " +"Para ferramentas de gravação de arquivo, é recomendável inserir apenas um " +"espaço entre a referência do objeto e o colchete esquerdo." -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "Uso para scripts" + +#: ../source/specifications/entry-points.rst:130 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -"Como regra geral, os instaladores devem, tanto quanto possível, preservar as " -"informações fornecidas na URL solicitada ao gerar :file:`direct_url.json`. " -"Por exemplo, as variáveis de ambiente usuário:senha devem ser preservadas e " -"``required_revision`` deve refletir a revisão que foi fornecida na URL " -"solicitada o mais fielmente possível. No entanto, essas informações são " -"*enriquecidas* com dados mais precisos, como ``commit_id``." - -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" -msgstr "Exemplo de comandos pip e seus efeitos em direct_url.json" - -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" -msgstr "Comandos que geram um ``direct_url.json``:" - -#: ../source/specifications/direct-url.rst:49 -#, fuzzy -msgid "``pip install https://example.com/app-1.0.tgz``" -msgstr "pip install https://example.com/app-1.0.tgz" - -#: ../source/specifications/direct-url.rst:50 -#, fuzzy -msgid "``pip install https://example.com/app-1.0.whl``" -msgstr "pip install https://example.com/app-1.0.whl" +"Dois grupos de pontos de entrada têm um significado especial no " +"empacotamento: ``console_scripts`` e ``gui_scripts``. Em ambos os grupos, o " +"nome do ponto de entrada deve ser usado como um comando em um shell do " +"sistema após a instalação do pacote. A referência do objeto aponta para uma " +"função que será chamada sem argumentos quando este comando for executado. A " +"função pode retornar um inteiro para ser usado como um código de saída do " +"processo, e retornar ``None`` é equivalente a retornar ``0``." -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:138 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" - -#: ../source/specifications/direct-url.rst:52 -#, fuzzy -msgid "``pip install ./app``" -msgstr "pip install ./app" - -#: ../source/specifications/direct-url.rst:53 -#, fuzzy -msgid "``pip install file:///home/user/app``" -msgstr "pip install file:///home/user/app" +"Por exemplo, o ponto de entrada ``mycmd = mymod:main`` criaria um comando " +"``mycmd`` lançando um script como este::" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:145 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (caso em que, ``url`` será o diretório local para " -"o qual o repositório git foi clonado e ``dir_info`` estará presente com " -"``\"editable\": true`` e nenhum ``vcs_info`` será definido)" - -#: ../source/specifications/direct-url.rst:58 -#, fuzzy -msgid "``pip install -e ./app``" -msgstr "pip install -e ./app" - -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" -msgstr "Comandos que *não* geram um ``direct_url.json``" - -#: ../source/specifications/direct-url.rst:62 -#, fuzzy -msgid "``pip install app``" -msgstr "pip install app" - -#: ../source/specifications/direct-url.rst:63 -#, fuzzy -msgid "``pip install app --no-index --find-links https://example.com/``" -msgstr "pip install app --no-index --find-links https://example.com/" +"A diferença entre ``console_scripts`` e ``gui_scripts`` afeta apenas os " +"sistemas Windows. ``console_scripts`` são empacotados em um executável de " +"console, então eles são anexados a um console e podem usar ``sys.stdin``, " +"``sys.stdout`` e ``sys.stderr`` para entrada e saída. ``gui_scripts`` são " +"empacotados em um executável GUI, então eles podem ser iniciados sem um " +"console, mas não podem usar streams padrão a menos que o código da aplicação " +"os redirecione. Outras plataformas não têm a mesma distinção." -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" -msgstr "Histórico" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" +"Espera-se que as ferramentas de instalação configurem wrappers para " +"``console_scripts`` e ``gui_scripts`` no diretório de scripts do esquema de " +"instalação. Eles não são responsáveis por colocar este diretório na variável " +"de ambiente ``PATH`` que define onde as ferramentas de linha de comando são " +"encontradas." -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:158 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -"Março de 2020: o arquivo de metadados ``direct_url.json`` foi originalmente " -"especificado na :pep:`610` e está formalmente documentado aqui." +"Como os arquivos são criados a partir dos nomes e alguns sistemas de " +"arquivos não fazem distinção entre maiúsculas e minúsculas, os pacotes devem " +"evitar o uso de nomes nesses grupos que diferem apenas em maiúsculas e " +"minúsculas. O comportamento das ferramentas de instalação quando os nomes " +"diferem apenas no caso de ser indefinido." -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" -msgstr "Estrutura de dados de URL direta" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "Ambiente gerenciado externamente" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -"Este documento especifica uma estrutura de dados abstrata serializável em " -"JSON que pode representar URLs para projetos python e artefatos de " -"distribuição, como árvores de fonte VCS, árvores de fonte local, " -"distribuições fonte e wheels." +"Embora algumas instalações do Python sejam totalmente gerenciadas pelo " +"usuário que instalou o Python, outras podem ser fornecidas e gerenciadas por " +"outros meios (como o gerenciador de pacotes do sistema operacional em uma " +"distribuição Linux ou como um ambiente integrado Python em um aplicativo com " +"um instalador dedicado)." -#: ../source/specifications/direct-url-data-structure.rst:12 -#, fuzzy -#| msgid "" -#| "The representation of the components of this data structure as a :rfc:" -#| "`1738` URL is not formally specified at time of writing. A common " -#| "representation is the pip URL format. Other examples are provided in :pep:" -#| "`440`." +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -"A representação dos componentes desta estrutura de dados como uma URL :rfc:" -"`1738` não é especificada formalmente no momento da escrita. Uma " -"representação comum é o formato de URL pip. Outros exemplos são fornecidos " -"em :pep:`440`." +"A tentativa de usar ferramentas de empacotamento convencionais Python para " +"manipular esses ambientes pode ser confusa, na melhor das hipóteses, e, na " +"pior das hipóteses, quebrar completamente todo o sistema operacional " +"subjacente. Os guias de documentação e interoperabilidade passam longe da " +"resolução de tais problemas." -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:18 +#, fuzzy msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -"A estrutura de dados da URL direta DEVE ser um dicionário serializável para " -"JSON de acordo com :rfc:`8259`." +"A :pep:`668` definiu um arquivo marcador ``EXTERNALLY-MANAGED`` que permite " +"que uma instalação do Python indique para ferramentas específicas do Python, " +"como ``pip``, que eles não instalam nem removem pacotes no ambiente de " +"instalação padrão do interpretador, e deve orientar o usuário final para " +"usar :ref:`virtual-environments`." -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -"DEVE conter pelo menos dois campos. O primeiro é ``url``, com tipo " -"``string``. Dependendo de qual ``url`` se refere, o segundo campo DEVE ser " -"um de ``vcs_info`` (se ``url`` é uma referência de VCS), ``archive_info`` " -"(se ``url`` é um pacote de código-fonte ou um wheel) ou ``dir_info`` (se " -"``url`` é um diretório local). Estes campos informacionais têm um " -"subdicionário (possivelmente vazio) como valor, com as chaves possíveis " -"definidas abaixo." -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -"Quando persistido, ``url`` DEVE ser podado a fim de retirar qualquer " -"informação sensível de autenticação, por razões de segurança." -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -"A seção usuário:senha da URL PODE, entretanto, ser composta de variáveis de " -"ambiente, correspondendo à seguinte expressão regular::" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +msgid "distro" +msgstr "distribution" + +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -"Além disso, a seção usuário:senha da URL PODE ser uma string bem conhecida e " -"não sensível à segurança. Um exemplo típico é ``git`` no caso de uma URL " -"como ``ssh://git@gitlab.com/user/repo``." - -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" -msgstr "URLs de VCS" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -"Quando a ``url`` faz referência a um repositório VCS, a chave ``vcs_info`` " -"DEVE estar presente como um dicionário com as seguintes chaves:" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -"Uma chave ``vcs`` (tipo ``string``) DEVE estar presente, contendo o nome do " -"VCS (ou seja, um de ``git``, ``hg``, ``bzr``, ``svn``). Outros VCS DEVERIAM " -"ser registrados escrevendo uma PEP para alterar esta especificação. O valor " -"``url`` DEVE ser compatível com o VCS correspondente, para que um instalador " -"possa entregá-lo sem transformação em um comando de checkout/download do VCS." -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -"Uma chave ``required_revision`` (tipo ``string``) PODE estar presente " -"nomeando um branch/tag/ref/commit/revisão/etc (em um formato compatível com " -"o VCS)." -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "empacotamento" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -"Uma chave ``commit_id`` (tipo ``string``) DEVE estar presente, contendo o " -"número exato de commit/revisão que foi/será instalado. Se o VCS oferecer " -"suporte a identificadores de revisão baseados em hash de commit, tal hash de " -"commit DEVE ser usado como ``commit_id`` para referenciar a versão imutável " -"do código-fonte." -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "URLs de arquivos" - -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -"Quando ``url`` se refere a um arquivo fonte ou wheel, a chave " -"``archive_info`` DEVE estar presente como um dicionário com as seguintes " -"chaves:" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -"Uma chave ``hashes`` DEVE estar presente como um dicionário mapeando um nome " -"de hash para um resumo de arquivo codificado em hex." -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +msgid "Python-specific package manager" +msgstr "O gerenciador de pacotes multiplataforma conda" + +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -"Vários hashes podem ser incluídos e cabe ao consumidor decidir o que fazer " -"com vários hashes (pode validar todos eles ou um subconjunto deles, ou nada)." -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -"Esses nomes de hash DEVEM sempre ser normalizados para letras minúsculas." -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -"Qualquer algoritmo de hash disponível via ``hashlib`` (especificamente " -"qualquer um que possa ser passado para ``hashlib.new()`` e não requeira " -"parâmetros adicionais) pode ser usado como uma chave para o dicionário de " -"hashes. Pelo menos um algoritmo seguro de ``hashlib.algorithms_guaranteed`` " -"DEVE sempre ser incluído. No momento da escrita, ``sha256`` especificamente " -"é recomendado." -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "Instaladores e gerenciadores de pacote para macOS" + +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -"Uma chave descontinuada ``hash`` (tipo ``string``) PODE estar presente para " -"fins de compatibilidade com versões anteriores, com valor ``=``." -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -"Os produtores da estrutura de dados DEVEM emitir a chave ``hashes`` se um ou " -"vários hashes estiverem disponíveis. Os produtores DEVEM continuar a emitir " -"a chave ``hash`` em contextos onde o faziam antes, de modo a manter a " -"compatibilidade com versões anteriores para clientes existentes." -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -"Quando as chaves ``hash`` e ``hashes`` estão presentes, o hash representado " -"na chave ``hash`` DEVE também estar presente no dicionário ``hashes``, para " -"que os consumidores possam considerar a chave ``hashes`` apenas se estiver " -"presente, e voltar para ``hash`` caso contrário." -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" -msgstr "Diretórios locais" +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +msgid "This specification is twofold." +msgstr "Especificações do PyPA" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -"Quando ``url`` se refere a um diretório local, a chave ``dir_info`` DEVE " -"estar presente como um dicionário com a seguinte chave:" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -"``editable`` (tipo: ``boolean``): ``true`` se a distribuição foi/será " -"instalada em modo editável, ``false`` caso contrário. Se ausente, é usado o " -"padrão ``false``." -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -"Quando ``url`` se refere a um diretório local, ele DEVE ter o esquema " -"``file`` e ser compatível com :rfc:`8089` Em particular, o componente do " -"caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao " -"tornar os caminhos relativos absolutos." -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" -msgstr "Projetos em subdiretórios" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -"Um campo ``subdirectory`` de nível superior PODE estar presente contendo um " -"caminho de diretório, relativo à raiz do repositório VCS, arquivo fonte ou " -"diretório local, para especificar onde ``pyproject.toml`` ou ``setup.py`` " -"está localizado." -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" -msgstr "VCS registrados" - -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -"Esta seção lista os VCS registrados; expandidos, informações específicas do " -"VCS sobre como usar ``vcs``, ``required_revision`` e outros campos de " -"``vcs_info``; e, em alguns casos, campos adicionais específicos de VCS. As " -"ferramentas PODEM oferecer suporte a outros VCS, embora seja RECOMENDADO " -"registrá-las escrevendo uma PEP para alterar esta especificação. O campo " -"``vcs`` DEVERIA ser o nome do comando (em letras minúsculas). Os campos " -"adicionais que seriam necessários para oferecer suporte a esse VCS DEVERIAM " -"ser prefixados com o nome do comando VCS." - -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" -msgstr "Git" - -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" -msgstr "Site" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" -msgstr "https://git-scm.com/" - -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" -msgstr "Comando vcs" - -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" -msgstr "git" - -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" -msgstr "Campo ``vcs``" - -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" -msgstr "Campo ``requested_revision``" - -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:170 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -"Um nome de tag, nome de branch, ref Git, hash de commit, hash de commit " -"encurtado ou outra coisa relacionada a commit." - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" -msgstr "Campo ``commit_id``" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." -msgstr "Um hash de confirmação (40 caracteres hexadecimais sha1)." - -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:173 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -"As ferramentas podem usar os comandos ``git show-ref`` e ``git symbolic-" -"ref`` para determinar se o ``required_revision`` corresponde a um ref Git. " -"Por sua vez, um ref começando com ``refs/tags/`` corresponde a uma tag, e um " -"ref começando com ``refs/remotes/origin/`` após a clonagem corresponde a um " -"branch." -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" -msgstr "Mercurial" - -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" -msgstr "hg" - -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -"Um nome de tag, nome de branch, ID de changeset, ID de changeset abreviado." - -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." -msgstr "Um ID de changeset (40 caracteres hexadecimais)." - -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" -msgstr "Bazaar" -#: ../source/specifications/direct-url-data-structure.rst:189 -#, fuzzy -#| msgid "https://www.mercurial-scm.org/" -msgid "https://www.breezy-vcs.org/" -msgstr "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" -msgstr "bzr" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." -msgstr "Um nome de tag, nome de branch, id de revisão." +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." -msgstr "Um id de revisão." +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" -msgstr "svn" - -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -"``requested_revision`` deve ser compatível com a opção ``--revision`` do " -"``svn checkout``. No Subversion, branch ou tag é parte de ``url``." -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:255 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -"Visto que o Subversion não oferece suporte a identificadores globalmente " -"únicos, este campo é o número da revisão do Subversion no repositório " -"correspondente." - -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" -msgstr "Arquivo fonte:" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" -msgstr "URL Git com tag e hash de commit:" - -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" -msgstr "Diretório local:" - -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" -msgstr "Diretório local em modo editável:" - -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:262 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -"Março de 2020: esta estrutura de dados foi originalmente especificada como " -"parte do arquivo de metadados ``direct_url.json`` em :pep:`610` e está " -"formalmente documentada aqui." -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:266 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -"Janeiro de 2023: Adicionada a chave ``archive_info.hashes`` (`discussão " -"`__)." - -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" -msgstr "Especificação de pontos de entrada" -#: ../source/specifications/entry-points.rst:7 -msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -"*Pontos de entrada* são um mecanismo para uma distribuição instalada " -"anunciar componentes que ela fornece para serem descobertos e usados por " -"outro código. Por exemplo:" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -"As distribuições podem especificar pontos de entrada ``console_scripts``, " -"cada um referindo-se a uma função. Quando *pip* (ou outro instalador " -"compatível com console_scripts) instala a distribuição, ele cria um wrapper " -"de linha de comando para cada ponto de entrada." -#: ../source/specifications/entry-points.rst:14 -msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -"As aplicações podem usar pontos de entrada para carregar plug-ins; por " -"exemplo, Pygments (uma ferramenta de realce de sintaxe) pode usar lexers e " -"estilos adicionais de pacotes instalados separadamente. Para mais " -"informações, consulte :doc:`/guides/creating-and-discovering-plugins`." -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:279 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -"O formato de arquivo de ponto de entrada foi originalmente desenvolvido para " -"permitir que pacotes construídos com setuptools forneçam metadados de ponto " -"de integração que seriam lidos em tempo de execução com ``importlib." -"metadata``. Ele agora é definido como uma especificação de " -"interoperabilidade PyPA a fim de permitir que outras ferramentas de " -"construção além do setuptools publiquem metadados de ponto de entrada " -"compatíveis com ``importlib.metadata`` e bibliotecas de tempo de execução " -"diferentes de ``importlib.metadata`` para ler portavelmente publicado " -"metadados de ponto de entrada (potencialmente com diferentes estratégias de " -"cache e resolução de conflitos)." - -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "Modelo de dados" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" -msgstr "" -"Conceitualmente, um ponto de entrada é definido por três propriedades " -"necessárias:" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Ativando um ambiente virtual" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -"O **grupo** ao qual um ponto de entrada pertence indica que tipo de objeto " -"ele fornece. Por exemplo, o grupo ``console_scripts`` é para pontos de " -"entrada referentes a funções que podem ser usadas como um comando, enquanto " -"``pygments.styles`` é o grupo para classes que definem estilos de pigmentos. " -"O consumidor normalmente define a interface esperada. Para evitar conflitos, " -"os consumidores que definem um novo grupo devem usar nomes começando com um " -"nome PyPI pertencente ao projeto do consumidor, seguido por ``.``. Os nomes " -"dos grupos devem ser um ou mais grupos de letras, números e sublinhados, " -"separados por pontos (regex ``^\\w+(\\.\\w+)*$``)." -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -"O **nome** identifica este ponto de entrada em seu grupo. O significado " -"preciso disso depende do cliente. Para scripts de console, o nome do ponto " -"de entrada é o comando que será usado para iniciá-lo. Em uma distribuição, " -"os nomes dos pontos de entrada devem ser exclusivos. Se distribuições " -"diferentes fornecerem o mesmo nome, o consumidor decide como lidar com tais " -"conflitos. O nome pode conter quaisquer caracteres, exceto ``=``, mas não " -"pode começar ou terminar com nenhum caractere de espaço em branco, ou " -"começar com ``[``. Para novos pontos de entrada, é recomendado usar apenas " -"letras, números, sublinhados, pontos e travessões (regex ``[\\w.-]+``)." -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -"A **referência de objeto** aponta para um objeto Python. Ele está no formato " -"``importable.module`` ou ``importable.module:object.attr``. Cada uma das " -"partes delimitadas por pontos e dois pontos é um identificador válido " -"Python. Destina-se a ser consultado assim::" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -"Algumas ferramentas chamam esse tipo de referência de objeto por si só de " -"\"ponto de entrada\", por falta de um termo melhor, especialmente quando " -"aponta para uma função para iniciar um programa." -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -"Há também uma propriedade opcional: os **extras** são um conjunto de strings " -"que identifica recursos opcionais da distribuição que fornece o ponto de " -"entrada. Se forem especificados, o ponto de entrada requer as dependências " -"desses 'extras'. Veja o campo de metadados :ref:`metadata_provides_extra`." -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -"Usar extras para um ponto de entrada não é mais recomendado. Os consumidores " -"devem oferecer suporte para analisá-los em distribuições existentes, mas " -"podem então ignorá-los. Novas ferramentas de publicação não precisam " -"suportar especificações extras. A funcionalidade de manipulação de extras " -"estava ligada ao modelo do setuptools de gerenciamento de pacotes \"egg\", " -"mas as ferramentas mais recentes, como pip e virtualenv, usam um modelo " -"diferente." -#: ../source/specifications/entry-points.rst:80 -msgid "File format" -msgstr "Formato de arquivo" +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -"Os pontos de entrada são definidos em um arquivo chamado :file:`entry_points." -"txt` no diretório :file:`*.dist-info` da distribuição. Este é o diretório " -"descrito em :ref:`recording-installed-packages` para distribuições " -"instaladas e em :ref:`binary-distribution-format` para wheels. O arquivo usa " -"a codificação de caracteres UTF-8." -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -"O conteúdo do arquivo está no formato INI, conforme lido pelo módulo :mod:" -"`configparser` do Python. No entanto, o configparser trata os nomes como não " -"diferenciando maiúsculas de minúsculas por padrão, enquanto os nomes de " -"pontos de entrada diferenciam maiúsculas de minúsculas. Um analisador de " -"configuração com distinção entre maiúsculas e minúsculas pode ser feito " -"assim::" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -"O arquivo de pontos de entrada deve sempre usar ``=`` para delimitar nomes " -"de valores (enquanto o configparser também permite o uso de ``:``)." -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -"As seções do arquivo de configuração representam grupos de pontos de " -"entrada, os nomes são nomes e os valores codificam a referência do objeto e " -"os extras opcionais. Se extras forem usados, eles serão uma lista separada " -"por vírgulas entre colchetes." -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -"Dentro de um valor, os leitores devem aceitar e ignorar os espaços " -"(incluindo vários espaços consecutivos) antes ou depois dos dois pontos, " -"entre a referência do objeto e o colchete esquerdo, entre os nomes extras e " -"os colchetes e dois pontos que os delimitam, e depois do quadrado direito " -"suporte. A sintaxe para extras é formalmente especificada como parte da :pep:" -"`508` (como ``extras``) e restrições em valores especificados na :pep:`685`. " -"Para ferramentas de gravação de arquivo, é recomendável inserir apenas um " -"espaço entre a referência do objeto e o colchete esquerdo." - -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "Por exemplo::" - -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" -msgstr "Uso para scripts" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -"Dois grupos de pontos de entrada têm um significado especial no " -"empacotamento: ``console_scripts`` e ``gui_scripts``. Em ambos os grupos, o " -"nome do ponto de entrada deve ser usado como um comando em um shell do " -"sistema após a instalação do pacote. A referência do objeto aponta para uma " -"função que será chamada sem argumentos quando este comando for executado. A " -"função pode retornar um inteiro para ser usado como um código de saída do " -"processo, e retornar ``None`` é equivalente a retornar ``0``." -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -"Por exemplo, o ponto de entrada ``mycmd = mymod:main`` criaria um comando " -"``mycmd`` lançando um script como este::" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -"A diferença entre ``console_scripts`` e ``gui_scripts`` afeta apenas os " -"sistemas Windows. ``console_scripts`` são empacotados em um executável de " -"console, então eles são anexados a um console e podem usar ``sys.stdin``, " -"``sys.stdout`` e ``sys.stderr`` para entrada e saída. ``gui_scripts`` são " -"empacotados em um executável GUI, então eles podem ser iniciados sem um " -"console, mas não podem usar streams padrão a menos que o código da aplicação " -"os redirecione. Outras plataformas não têm a mesma distinção." -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "Tipos de documentação" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -"Espera-se que as ferramentas de instalação configurem wrappers para " -"``console_scripts`` e ``gui_scripts`` no diretório de scripts do esquema de " -"instalação. Eles não são responsáveis por colocar este diretório na variável " -"de ambiente ``PATH`` que define onde as ferramentas de linha de comando são " -"encontradas." -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -"Como os arquivos são criados a partir dos nomes e alguns sistemas de " -"arquivos não fazem distinção entre maiúsculas e minúsculas, os pacotes devem " -"evitar o uso de nomes nesses grupos que diferem apenas em maiúsculas e " -"minúsculas. O comportamento das ferramentas de instalação quando os nomes " -"diferem apenas no caso de ser indefinido." -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" -msgstr "Ambiente gerenciado externamente" +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "pip install app" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -"Embora algumas instalações do Python sejam totalmente gerenciadas pelo " -"usuário que instalou o Python, outras podem ser fornecidas e gerenciadas por " -"outros meios (como o gerenciador de pacotes do sistema operacional em uma " -"distribuição Linux ou como um ambiente integrado Python em um aplicativo com " -"um instalador dedicado)." -#: ../source/specifications/externally-managed-environments.rst:13 -msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +msgid "``pip install --prefix=/some/path``" +msgstr "pip install -e ./app" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -"A tentativa de usar ferramentas de empacotamento convencionais Python para " -"manipular esses ambientes pode ser confusa, na melhor das hipóteses, e, na " -"pior das hipóteses, quebrar completamente todo o sistema operacional " -"subjacente. Os guias de documentação e interoperabilidade passam longe da " -"resolução de tais problemas." -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/externally-managed-environments.rst:428 #, fuzzy -#| msgid "" -#| ":pep:`668` defined an ``EXTERNALLY-MANAGED`` marker file that allows a " -#| "Python installation to indicate to Python-specific tools such as ``pip`` " -#| "that they neither install nor remove packages into the interpreter’s " -#| "default installation environment, and should instead guide the end user " -#| "towards using :ref:`virtual-environments`." +msgid "``pip install --user``" +msgstr "pip install -e ./app" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -"A :pep:`668` definiu um arquivo marcador ``EXTERNALLY-MANAGED`` que permite " -"que uma instalação do Python indique para ferramentas específicas do Python, " -"como ``pip``, que eles não instalam nem removem pacotes no ambiente de " -"instalação padrão do interpretador, e deve orientar o usuário final para " -"usar :ref:`virtual-environments`." -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -#, fuzzy -#| msgid "distribution" -msgid "distro" -msgstr "distribution" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Diretos autorais" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 -msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." -msgstr "" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Especificações do PyPA" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/index.rst:6 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" +"Esta é uma lista de especificações de interoperabilidade atualmente ativas " +"mantidas pela Python Packaging Authority. O processo de atualização desses " +"padrões e de proposição de novos está documentado em `pypa.io `__." -#: ../source/specifications/externally-managed-environments.rst:79 +#: ../source/specifications/inline-script-metadata.rst:3 #, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "empacotamento" +msgid "Inline script metadata" +msgstr "Declarando os metadados do projeto" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "The conda cross-platform package manager" -msgid "Python-specific package manager" -msgstr "O gerenciador de pacotes multiplataforma conda" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -#, fuzzy -#| msgid "macOS installers and package managers" -msgid "distro package manager" -msgstr "Instaladores e gerenciadores de pacote para macOS" +#: ../source/specifications/inline-script-metadata.rst:59 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 +#: ../source/specifications/inline-script-metadata.rst:79 #, fuzzy -#| msgid "PyPA specifications" -msgid "This specification is twofold." -msgstr "Especificações do PyPA" +msgid "pyproject type" +msgstr "pyproject.toml" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 -msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:98 +msgid "" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" +msgstr "Exemplo" + +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +msgid "Reference Implementation" +msgstr "Tipos de documentação" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +msgid "Recommendations" +msgstr "Recomendações de ferramentas" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" +msgstr "Normalização de nome de pacote" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" +"Os nomes dos projetos são \"normalizados\" para uso em vários contextos. " +"Este documento descreve como os nomes dos projetos devem ser normalizados." -#: ../source/specifications/externally-managed-environments.rst:255 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "Nomes não normalizados válidos" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" +"Um nome válido consiste apenas em letras e números ASCII, ponto, sublinhado " +"e hífen. Deve começar e terminar com uma letra ou número. Isso significa que " +"nomes de projeto válidos são limitados àqueles que correspondem ao seguinte " +"regex (executado com ``re.IGNORECASE``)::" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" +msgstr "Normalização" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" +"O nome deve ser colocado em letras minúsculas com todos os caracteres ``.``, " +"``-`` ou ``_`` substituídos por um único caractere ``-``. Isso pode ser " +"implementado em Python com o módulo re:" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" +msgstr "Isso significa que os seguintes nomes são todos equivalentes:" + +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" +msgstr "``friendly-bard`` (forma normalizada)" + +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" +msgstr "``Friendly-Bard``" + +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" +msgstr "``FRIENDLY-BARD``" + +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" +msgstr "``friendly.bard``" + +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" +msgstr "``friendly_bard``" + +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "``friendly--bard``" + +#: ../source/specifications/name-normalization.rst:39 +#, fuzzy msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" +"``FrIeNdLy-._.-bArD`` (uma forma _terrível_ de descrever um nome, mas é " +"válida)" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Tags de compatibilidade de plataforma" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" +"As tags de compatibilidade de plataforma permitem que ferramentas de " +"construção marquem as distribuições como sendo compatíveis com plataformas " +"específicas e permitem que os instaladores entendam quais distribuições são " +"compatíveis com o sistema em que estão executando." -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -msgid "Guide users towards virtual environments" -msgstr "Ativando um ambiente virtual" +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" +msgstr "Os seguintes PEPs contribuíram para esta especificação:" + +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" +msgstr ":pep:`425`" + +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" +msgstr ":pep:`513`" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" +msgstr ":pep:`571`" + +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" +msgstr ":pep:`599`" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" +msgstr ":pep:`600`" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "Oformato da tag é ``{python tag}-{abi tag}-{platform tag}``." + +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" +msgstr "python tag" + +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" +msgstr "'py27', 'cp33'" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" +msgstr "'cp32dmu', 'none'" + +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" +msgstr "'linux_x86_64', 'any'" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" +"Por exemplo, a tag ``py27-none-any`` indica compatibilidade com Python 2.7 " +"(qualquer implementação Python 2.7), com nenhum requisito de ABI, em " +"qualquer plataforma." -#: ../source/specifications/externally-managed-environments.rst:293 +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "Uso" + +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" +"O formato de pacote construído ``wheel`` inclui essas tags em seus nomes de " +"arquivo, no formato ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abitag}-{platform tag} .whl``. Outros formatos de pacote podem ter suas " +"próprias convenções." -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" +"Quaisquer espaços em potencial em alguma tag deve ser substituído por ``_``." -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" +msgstr "A tag Python" + +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" +"A tag Python indica a implementação e a versão exigida por uma distribuição. " +"As principais implementações têm códigos abreviados, inicialmente:" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: Python genérico (não requer recursos específicos de implementação)" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" +msgstr "cp: CPython" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" +msgstr "ip: IronPython" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" +msgstr "pp: PyPy" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" +msgstr "jy: Jython" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." +msgstr "Outras implementações Python devem usar ``sys.implementation.name``." -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" +"A versão é ``py_version_nodot``. CPython fica sem ponto, mas se um for " +"necessário, o sublinhado ``_`` é usado em seu lugar. PyPy provavelmente deve " +"usar suas próprias versões aqui ``pp18``, ``pp19``." -#: ../source/specifications/externally-managed-environments.rst:377 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" +"A versão pode ser apenas a versão principal ``2`` ou ``3`` ``py2``, ``py3`` " +"para muitas distribuições de Python puro." -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" +"É importante ressaltar que as tags somente da versão principal, como ``py2`` " +"e ``py3``, não são abreviações para ``py20`` e ``py30``. Em vez disso, essas " +"tags significam que o empacotador lançou intencionalmente uma distribuição " +"compatível com várias versões." -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" +"Uma distribuição compatível com Python 2/3 de fonte única pode usar a tag " +"composta ``py2.py3``. Consulte `Conjuntos de tags compactadas`_, abaixo." -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "A tag ABI" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" +"A tag ABI indica qual ABI do Python é necessária para qualquer módulo de " +"extensão incluído. Para ABIs específicos de implementação, a implementação é " +"abreviada da mesma forma que a tag Python, por exemplo ``cp33d`` seria o ABI " +"CPython 3.3 com depuração." -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Tipos de documentação" - -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" +"A ABI estável do CPython é ``abi3`` como no sufixo da biblioteca " +"compartilhada." -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" +"Implementações com uma ABI muito instável podem usar os primeiros 6 bytes " +"(como 8 caracteres codificados em base64) do hash SHA-256 de sua revisão de " +"código-fonte e sinalizadores de compilador, etc, mas provavelmente não terão " +"uma grande necessidade de distribuir distribuições binárias. A comunidade de " +"cada implementação pode decidir como usar melhor a tag ABI." -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -msgid "``pip install``" -msgstr "pip install app" +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "A tag Platform" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:95 +#, fuzzy msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" +"A tag da plataforma é simplesmente ``distutils.util.get_platform()`` com " +"todos os hífens ``-`` e pontos ``.`` substituídos por sublinhados ``_``." -#: ../source/specifications/externally-managed-environments.rst:425 -#, fuzzy -msgid "``pip install --prefix=/some/path``" -msgstr "pip install -e ./app" +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" +msgstr "win32" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" +msgstr "linux_i386" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -msgid "``pip install --user``" -msgstr "pip install -e ./app" +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "linux_x86_64" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" +msgstr "``manylinux``" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" +"O esquema definido na :pep:`425` é insuficiente para distribuição pública de " +"arquivos wheel (e arquivos wheel do \\*nix em geral) para plataformas Linux, " +"devido ao grande ecossistema de plataformas Linux e diferenças sutis entre " +"elas." -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" +"Em vez disso, a :pep:`600` define o padrão ``manylinux``, que representa um " +"subconjunto comum de plataformas Linux, e permite a construção de wheels com " +"a tag de plataforma ``manylinux`` que pode ser usada na maioria das " +"distribuições Linux." -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" +"Houve várias iterações da especificação ``manylinux``, cada uma " +"representando o subconjunto comum de plataformas Linux em um determinado " +"ponto no tempo:" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" +"``manylinux1`` (:pep:`513`) oferece suporte às arquiteturas ``x86_64`` e " +"``i686`` e é baseado em uma plataforma Linux compatível de 2007." -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" +"``manylinux2010`` (:pep:`571`) oferece suporte às arquiteturas ``x86_64`` e " +"``i686`` e atualiza a especificação anterior para se basear em uma " +"plataforma Linux compatível a partir de 2010." -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" -msgstr "Especificações do PyPA" - -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -"Esta é uma lista de especificações de interoperabilidade atualmente ativas " -"mantidas pela Python Packaging Authority. O processo de atualização desses " -"padrões e de proposição de novos está documentado em `pypa.io `__." - -#: ../source/specifications/inline-script-metadata.rst:3 -#, fuzzy -#| msgid "Declaring project metadata" -msgid "Inline script metadata" -msgstr "Declarando os metadados do projeto" +"``manylinux2014`` (:pep:`599`) adiciona suporte para várias arquiteturas " +"adicionais (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le`` e ``s390x``) e " +"atualiza a plataforma base para uma plataforma Linux compatível de 2014." -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" +"``manylinux_x_y`` (:pep:`600`) substitui todas as PEPs anteriores para " +"definir um padrão à prova de futuro. Ele define ``x`` e ``y`` como as " +"versões principais e secundárias do glibc suportadas (por exemplo, " +"``manylinux_2_24`` deve funcionar em qualquer distro usando glibc 2.24+). " +"Tags anteriores ainda são suportadas para compatibilidade com versões " +"anteriores." -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" +"Em geral, as distribuições construídas para versões mais antigas da " +"especificação são compatíveis com versões futuras (o que significa que as " +"distribuições ``manylinux1`` devem continuar a funcionar em sistemas " +"modernos), mas não compatíveis com versões anteriores (significando que " +"distribuições ``manylinux2010`` não devem trabalhar em plataformas que " +"existiam antes de 2010)." -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" +"Os mantenedores do pacote devem tentar atingir a especificação mais " +"compatível possível, com a ressalva de que o ambiente de compilação " +"fornecido para ``manylinux1`` e ``manylinux2010`` atingiu o fim da vida, o " +"que significa que essas imagens não receberão mais atualizações de segurança." -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" +msgstr "Suporte a compatibilidade de manylinux" + +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" +"A especificação de ``manylinux2014`` é relativamente nova e ainda não é " +"amplamente reconhecida pelas ferramentas de instalação." -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" +"A especificação de ``manylinux_x_y`` é relativamente nova e não é amplamente " +"reconhecida pelas ferramentas de instalação." -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" +"A tabela a seguir mostra as versões mínimas de projetos relevantes para " +"oferecer suporte aos vários padrões ``manylinux``:" -#: ../source/specifications/inline-script-metadata.rst:56 -msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" +msgstr "Ferramenta" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" +"Suporte somente para ``manylinux_2_24`` foi adicionado em auditwheel 3.3.0" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" -msgstr "Exemplo" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Tipos de documentação" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Tool recommendations" -msgid "Recommendations" -msgstr "Recomendações de ferramentas" - -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" -msgstr "Normalização de nome de pacote" - -#: ../source/specifications/name-normalization.rst:7 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -"Os nomes dos projetos são \"normalizados\" para uso em vários contextos. " -"Este documento descreve como os nomes dos projetos devem ser normalizados." - -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" -msgstr "Nomes não normalizados válidos" -#: ../source/specifications/name-normalization.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:261 msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -"Um nome válido consiste apenas em letras e números ASCII, ponto, sublinhado " -"e hífen. Deve começar e terminar com uma letra ou número. Isso significa que " -"nomes de projeto válidos são limitados àqueles que correspondem ao seguinte " -"regex (executado com ``re.IGNORECASE``)::" - -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" -msgstr "Normalização" -#: ../source/specifications/name-normalization.rst:22 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -"O nome deve ser colocado em letras minúsculas com todos os caracteres ``.``, " -"``-`` ou ``_`` substituídos por um único caractere ``-``. Isso pode ser " -"implementado em Python com o módulo re:" - -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" -msgstr "Isso significa que os seguintes nomes são todos equivalentes:" - -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" -msgstr "``friendly-bard`` (forma normalizada)" - -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" -msgstr "``Friendly-Bard``" - -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" -msgstr "``FRIENDLY-BARD``" - -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" -msgstr "``friendly.bard``" - -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" -msgstr "``friendly_bard``" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" -msgstr "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" -#: ../source/specifications/name-normalization.rst:39 -#, fuzzy -#| msgid "" -#| "``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:264 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -"``FrIeNdLy-._.-bArD`` (uma forma _terrível_ de descrever um nome, mas é " -"válida)" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:272 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:269 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" -msgstr "Tags de compatibilidade de plataforma" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -"As tags de compatibilidade de plataforma permitem que ferramentas de " -"construção marquem as distribuições como sendo compatíveis com plataformas " -"específicas e permitem que os instaladores entendam quais distribuições são " -"compatíveis com o sistema em que estão executando." - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" -msgstr "Os seguintes PEPs contribuíram para esta especificação:" - -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" -msgstr ":pep:`425`" - -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" -msgstr ":pep:`513`" - -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" -msgstr ":pep:`571`" - -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" -msgstr ":pep:`599`" - -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" -msgstr ":pep:`600`" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." -msgstr "Oformato da tag é ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" -msgstr "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" -msgstr "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" -msgstr "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" -msgstr "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -"Por exemplo, a tag ``py27-none-any`` indica compatibilidade com Python 2.7 " -"(qualquer implementação Python 2.7), com nenhum requisito de ABI, em " -"qualquer plataforma." - -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" -msgstr "Uso" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:303 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -"O formato de pacote construído ``wheel`` inclui essas tags em seus nomes de " -"arquivo, no formato ``{distribution}-{version}(-{build tag})?-{python tag}-" -"{abitag}-{platform tag} .whl``. Outros formatos de pacote podem ter suas " -"próprias convenções." -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -"Quaisquer espaços em potencial em alguma tag deve ser substituído por ``_ ``." -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" -msgstr "A tag Python" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "O arquivo :file:`.pypirc`" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -"A tag Python indica a implementação e a versão exigida por uma distribuição. " -"As principais implementações têm códigos abreviados, inicialmente:" - -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" -msgstr "py: Python genérico (não requer recursos específicos de implementação)" +"Um arquivo :file:`.pypirc` permite que você defina a configuração para :term:" +"`índices de pacotes <Índice de Pacotes>` (referido aqui como " +"\"repositórios\"), para que você não precise inserir a URL, nome de usuário " +"ou senha sempre que você enviar um pacote com :ref:`twine` ou :ref:`flit`." -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" -msgstr "cp: CPython" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "O formato (originalmente definido pelo pacote :ref:`distutils`) é:" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" -msgstr "ip: IronPython" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" +"A seção ``distutils`` define um campo ``index-servers`` que lista o nome de " +"todas as seções descrevendo um repositório." -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" -msgstr "pp: PyPy" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" +msgstr "Cada seção descrevendo um repositório define três campos:" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" -msgstr "jy: Jython" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." +msgstr "``repository``: A URL do repositório." -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." -msgstr "Outras implementações Python devem usar ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "``username``: O nome de usuário registrado no repositório." -#: ../source/specifications/platform-compatibility-tags.rst:62 -msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -"A versão é ``py_version_nodot``. CPython fica sem ponto, mas se um for " -"necessário, o sublinhado ``_`` é usado em seu lugar. PyPy provavelmente deve " -"usar suas próprias versões aqui ``pp18``, ``pp19``." +"``password``: A senha que será usada para autenticar o nome de usuário." -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -"A versão pode ser apenas a versão principal ``2`` ou ``3`` ``py2``, ``py3`` " -"para muitas distribuições de Python puro." +"Esteja ciente de que isso armazena sua senha em texto simples. Para melhor " +"segurança, considere uma alternativa como `chaveiro`_, configurando " +"variáveis de ambiente ou fornecendo a senha na linha de comando." -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/pypirc.rst:47 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -"É importante ressaltar que as tags somente da versão principal, como ``py2`` " -"e ``py3``, não são abreviações para ``py20`` e ``py30``. Em vez disso, essas " -"tags significam que o empacotador lançou intencionalmente uma distribuição " -"compatível com várias versões." +"Caso contrário, defina as permissões em :file:`.pypirc` para que somente " +"você possa ver ou modificá-lo. Por exemplo, no Linux ou macOS, execute:" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" +msgstr "Configurações comuns" + +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -"Uma distribuição compatível com Python 2/3 de fonte única pode usar a tag " -"composta ``py2.py3``. Consulte `Conjuntos de tags compactadas`_, abaixo." - -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" -msgstr "A tag ABI" +"Esses exemplos se aplicam a :ref:`twine`. Outros projetos (por exemplo, :ref:" +"`flit`) também usam :file:`.pypirc`, mas com padrões diferentes. Consulte a " +"documentação de cada projeto para obter mais detalhes e instruções de uso." -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:65 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -"A tag ABI indica qual ABI do Python é necessária para qualquer módulo de " -"extensão incluído. Para ABIs específicos de implementação, a implementação é " -"abreviada da mesma forma que a tag Python, por exemplo ``cp33d`` seria o ABI " -"CPython 3.3 com depuração." +"A configuração padrão do Twine imita um :file:`.pypirc` com seções de " +"repositório para PyPI e TestPyPI:" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:81 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -"A ABI estável do CPython é ``abi3`` como no sufixo da biblioteca " -"compartilhada." +"Twine irá adicionar configuração adicional de :file:`$HOME/.pypirc`, a linha " +"de comando e variáveis de ambiente a esta configuração padrão." -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" +msgstr "Usando um token do PyPI" + +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -"Implementações com uma ABI muito instável podem usar os primeiros 6 bytes " -"(como 8 caracteres codificados em base64) do hash SHA-256 de sua revisão de " -"código-fonte e sinalizadores de compilador, etc, mas provavelmente não terão " -"uma grande necessidade de distribuir distribuições binárias. A comunidade de " -"cada implementação pode decidir como usar melhor a tag ABI." - -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" -msgstr "A tag Platform" +"Para definir seu `token de API`_ para PyPI, você pode criar um :file:`$HOME/." +"pypirc` semelhante a:" -#: ../source/specifications/platform-compatibility-tags.rst:95 -#, fuzzy -#| msgid "" -#| "The platform tag is simply ``distutils.util.get_platform()`` with all " -#| "hyphens ``-`` and periods ``.`` replaced with underscore ``_``." +#: ../source/specifications/pypirc.rst:96 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -"A tag da plataforma é simplesmente ``distutils.util.get_platform()`` com " -"todos os hífens ``-`` e pontos ``.`` substituídos por sublinhados ``_``." +"Para o :ref:`TestPyPI `, adicione a seção ``[testpypi]``, " +"usando o token de API de sua conta do TestPyPI." -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" -msgstr "win32" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" +msgstr "Usando outro índice de pacotes" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" -msgstr "linux_i386" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" +"Para configurar um repositório adicional, você precisará redefinir o campo " +"``index-servers`` para incluir o nome do repositório. Aqui está um exemplo " +"completo de um :file:`$HOME/.pypirc` para PyPI, TestPyPI e um repositório " +"privado:" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" -msgstr "linux_x86_64" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" +"Em vez de usar o campo ``password``, considere salvar seus tokens de API e " +"senhas com segurança usando um `chaveiro`_ (que é instalado pelo Twine):" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" -msgstr "``manylinux``" +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +msgid "``pyproject.toml`` specification" +msgstr "``pyproject.toml`` é obrigatório?" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -"O esquema definido na :pep:`425` é insuficiente para distribuição pública de " -"arquivos wheel (e arquivos wheel do \\*nix em geral) para plataformas Linux, " -"devido ao grande ecossistema de plataformas Linux e diferenças sutis entre " -"elas." -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -"Em vez disso, a :pep:`600` define o padrão ``manylinux``, que representa um " -"subconjunto comum de plataformas Linux, e permite a construção de wheels com " -"a tag de plataforma ``manylinux`` que pode ser usada na maioria das " -"distribuições Linux." -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -"Houve várias iterações da especificação ``manylinux``, cada uma " -"representando o subconjunto comum de plataformas Linux em um determinado " -"ponto no tempo:" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:29 +#, fuzzy +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "Declarando dependências do sistema de construção" + +#: ../source/specifications/pyproject-toml.rst:31 +#, fuzzy msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -"``manylinux1`` (:pep:`513`) oferece suporte às arquiteturas ``x86_64`` e " -"``i686`` e é baseado em uma plataforma Linux compatível de 2007." +"`pyproject.toml` é um formato de arquivo independente do sistema de " +"construção definido na :pep:`518` que os projetos podem fornecer para " +"declarar quaisquer dependências de nível Python que devem ser instaladas " +"para executar o sistema de construção do projeto com sucesso." -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -"``manylinux2010`` (:pep:`571`) oferece suporte às arquiteturas ``x86_64`` e " -"``i686`` e atualiza a especificação anterior para se basear em uma " -"plataforma Linux compatível a partir de 2010." +"A tabela ``[build-system]`` é usada para armazenar dados relacionados a " +"construção. Inicialmente, apenas uma chave da tabela é válida e é " +"obrigatória para a tabela: ``requires``. Esta chave deve ter um valor de uma " +"lista de strings que representam dependências necessárias para executar o " +"sistema de construção. As strings nesta lista seguem a :ref:`especificação " +"de especificadores de versão `." -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -"``manylinux2014`` (:pep:`599`) adiciona suporte para várias arquiteturas " -"adicionais (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le`` e ``s390x``) e " -"atualiza a plataforma base para uma plataforma Linux compatível de 2014." -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -"``manylinux_x_y`` (:pep:`600`) substitui todas as PEPs anteriores para " -"definir um padrão à prova de futuro. Ele define ``x`` e ``y`` como as " -"versões principais e secundárias do glibc suportadas (por exemplo, " -"``manylinux_2_24`` deve funcionar em qualquer distro usando glibc 2.24+). " -"Tags anteriores ainda são suportadas para compatibilidade com versões " -"anteriores." -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -"Em geral, as distribuições construídas para versões mais antigas da " -"especificação são compatíveis com versões futuras (o que significa que as " -"distribuições ``manylinux1`` devem continuar a funcionar em sistemas " -"modernos), mas não compatíveis com versões anteriores (significando que " -"distribuições ``manylinux2010`` não devem trabalhar em plataformas que " -"existiam antes de 2010)." -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -"Os mantenedores do pacote devem tentar atingir a especificação mais " -"compatível possível, com a ressalva de que o ambiente de compilação " -"fornecido para ``manylinux1`` e ``manylinux2010`` atingiu o fim da vida, o " -"que significa que essas imagens não receberão mais atualizações de segurança." -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" -msgstr "Suporte a compatibilidade de manylinux" +#: ../source/specifications/pyproject-toml.rst:103 +#, fuzzy +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "Declarando os metadados do projeto" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -"A especificação de ``manylinux2014`` é relativamente nova e ainda não é " -"amplamente reconhecida pelas ferramentas de instalação." -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -"A especificação de ``manylinux_x_y`` é relativamente nova e não é amplamente " -"reconhecida pelas ferramentas de instalação." +"Existem dois tipos de metadados: *estáticos* e *dinâmicos*. Metadados " +"estáticos são especificados diretamente no arquivo ``pyproject.toml`` e não " +"podem ser especificados ou alterados por uma ferramenta (isso inclui dados " +"*referenciados* pelo metadados, por exemplo, o conteúdo de arquivos " +"referenciados pelos metadados). Os metadados dinâmicos são listados por meio " +"da chave ``dynamic`` (definido posteriormente nesta especificação) e " +"representam os metadados que uma ferramenta fornecerá posteriormente." -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -"A tabela a seguir mostra as versões mínimas de projetos relevantes para " -"oferecer suporte aos vários padrões ``manylinux``:" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "Ferramenta" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" -msgstr "``manylinux1``" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" -msgstr "``manylinux2010``" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" -msgstr "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" +msgstr "As únicas chaves que precisam ser definidos estaticamente são:" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" -msgstr "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" +"As chaves que são obrigatórias, mas podem ser especificadas estaticamente " +"*ou* listadas como dinâmicas são:" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" -msgstr "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"Todas as outras chaves são consideradas opcionais e podem ser especificadas " +"estaticamente, listadas como dinâmicas ou não especificadas." -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" -msgstr "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "A lista completa de chaves permitidas na tabela ``[project]`` são:" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" -msgstr "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" +msgstr "``authors``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" -msgstr "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" +msgstr "``dependencies``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "auditwheel" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" +msgstr "``dynamic``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" +msgstr "``entry-points``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" -msgstr "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" +msgstr "``maintainers``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" +msgstr "``optional-dependencies``" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" -msgstr "" -"Suporte somente para ``manylinux_2_24`` foi adicionado em auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" +msgstr "Tipo TOML_: string" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Name `" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." +msgstr "O nome do projeto." + +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" +"As ferramentas DEVEM :ref:`normalizar ` este nome, " +"conforme especificado por :pep:`503`, assim que for lido para consistência " +"interna." -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Version `" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" +"A versão do projeto, conforme definido na :ref:`especificação de " +"especificadores de versão `." -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "Os usuários DEVEM preferir especificar versões já normalizadas." -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Summary `" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." +msgstr "A descrição resumida do projeto." -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" +msgstr "Tipo TOML_: string ou tabela" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" +"Campos correspondente dos :ref:`metadados principais `: :ref:" +"`Description ` e :ref:`Description-Content-Type " +"`" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." +msgstr "A descrição completa do projeto (isto é, o README)." -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" +"A chave aceita uma string ou uma tabela. Se for uma string, então é um " +"caminho relativo ao ``pyproject.toml`` para um arquivo texto contendo a " +"descrição completa. As ferramentas DEVEM presumir que a codificação do " +"arquivo é UTF-8. Se o caminho do arquivo termina com um sufixo ``.md``, ou " +"sua versão em caixa alta, então as ferramentas DEVEM presumir que o tipo de " +"conteúdo é ``text/markdown``. Se o caminho do arquivo termina em ``.rst``, " +"então as ferramentas DEVEM presumir que o tipo de conteúdo é ``text/x-rst``. " +"Se uma ferramenta reconhece mais extensões do que esta PEP, elas podem " +"inferir o tipo de conteúdo para o usuário sem especificar esta chave como " +"``dynamic``. Para todos os sufixos não reconhecidos quando um tipo de " +"conteúdo não é fornecido, as ferramentas DEVEM levantar um erro." -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" +"A chave ``readme`` também pode receber uma tabela. A chave ``file`` tem um " +"valor string que representa um caminho relativo a ``pyproject.toml`` para um " +"arquivo contendo a descrição completa. A chave ``text`` tem um valor de " +"string que é a descrição completa. Essas chaves são mutuamente exclusivas, " +"portanto, as ferramentas DEVEM levantar um erro se os metadados " +"especificarem ambas as chaves." -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" +"Uma tabela especificada na chave ``readme`` também possui uma chave " +"``content-type`` que recebe uma string especificando o tipo de conteúdo da " +"descrição completa. Uma ferramenta DEVE levantar um erro se os metadados não " +"especificarem esse campo na tabela. Se os metadados não especificarem o " +"parâmetro ``charset``, será considerado UTF-8. As ferramentas PODEM oferecer " +"suporte a outras codificações, se assim o desejarem. As ferramentas PODEM " +"oferecer suporte a tipos de conteúdo alternativos que podem transformar em " +"um tipo de conteúdo conforme suportado pelos :ref:`metadados principais " +"`. Caso contrário, as ferramentas DEVEM levantar um erro para " +"tipos de conteúdo não suportados." -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Requires-Python `" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." +msgstr "Os requisitos de versão do Python do projeto." -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" +msgstr "Tipo TOML_: tabela" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`License `" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" +"A tabela pode ter uma de duas chaves. A chave ``file`` tem um valor de " +"string que é um caminho de arquivo relativo a ``pyproject.toml`` para o " +"arquivo que contém a licença do projeto. As ferramentas DEVEM presumir que a " +"codificação do arquivo é UTF-8. A chave ``text`` tem um valor de string que " +"é a licença do projeto. Essas chaves são mutuamente exclusivas, portanto, " +"uma ferramenta DEVE levantar um erro se os metadados especificarem ambas as " +"chaves." -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "Tipo TOML_: Vetor de tabelas em linha com strings de chaves e valores" + +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" +"Campos correspondentes dos :ref:`metadados principais `: :ref:" +"`Author `, :ref:`Author-email `, :ref:`Maintainer ` e :ref:`Maintainer-" +"email `" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" +"As pessoas ou organizações consideradas \"autoras\" do projeto. O " +"significado exato está aberto à interpretação -- pode listar os autores " +"originais ou primários, mantenedores atuais ou proprietários do pacote." -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" +"A chave \"maintainers\" é semelhante a \"authors\" no sentido de que seu " +"significado exato está aberto à interpretação." -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" +"Estas chaves aceitam um vetor de tabelas com 2 chaves: ``name`` e ``email``. " +"Ambos os valores devem ser strings. O valor ``name`` DEVE ser um nome de e-" +"mail válido (ou seja, o que quer que possa ser colocado como um nome, antes " +"de um e-mail, em :rfc:`822`) e não conter vírgulas. O valor ``email`` DEVE " +"ser um endereço de email válido. Ambas as chaves são opcionais, mas ao menos " +"uma das chaves deve ser especificada na tabela." -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" +"O uso dos dados para preencher :ref:`metadados principais ` " +"deve ser feito da seguinte forma:" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" +"Se somente ``name`` for fornecido, o valor vai em :ref:`Author ` ou :ref:`Maintainer ` conforme " +"apropriado." -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" +"Se somente ``email`` é fornecido, o valor vai em :ref:`Author-email ` ou :ref:`Maintainer-email ` conforme apropriado." -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" +"Se ``email`` e ``name`` são fornecidos, o valor vai em :ref:`Author-email " +"` ou :ref:`Maintainer-email ` conforme apropriado, com o formado ``{name} <{email}>``." -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." +msgstr "Vários valores devem ser separados por vírgulas." + +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "Tipo TOML_: vetor de strings" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Keywords `" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." +msgstr "As palavras-chave do projeto." -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Classifier `" -#: ../source/specifications/platform-compatibility-tags.rst:272 +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." +msgstr "Classificadores Trove que se aplicam ao projeto." + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" +msgstr "Tipo TOML_: tabela com chaves e valores de strings" + +#: ../source/specifications/pyproject-toml.rst:316 msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Project-URL `" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" +"Uma tabela de URLs onde a chave é o rótulo da URL e o valor é a URL em si." -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" +msgstr "Pontos de entrada" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" +"Tipo TOML_: tabela (``[project.scripts]``, ``[project.gui-scripts]`` e " +"``[project.entry-points]``)" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Especificação de pontos de entrada `" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" +"Existem três tabelas relacionadas aos pontos de entrada. A tabela ``[project." +"scripts]`` corresponde ao grupo ``console_scripts`` na :ref:`especificação " +"de pontos de entrada `. A chave da tabela é o nome do ponto de " +"entrada e o valor é a referência do objeto." -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" +"A tabela ``[project.gui-scripts]`` corresponde ao grupo ``gui_scripts`` na :" +"ref:`especificação de pontos de entrada `. Seu formato é o " +"mesmo que ``[project.scripts]``." -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" +"A tabela ``[project.entry-points]`` é uma coleção de tabelas. O nome de cada " +"subtabela é um grupo de pontos de entrada. A chave e a semântica do valor " +"são iguais a ``[project.scripts]``. Os usuários NÃO DEVEM criar subtabelas " +"aninhadas, mas sim manter os grupos de pontos de entrada em apenas um nível " +"de profundidade." -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" +"Backends de construção DEVEM levantar um erro se os metadados definem uma " +"tabela ``[project.entry-points.console_scripts]`` ou ``[project.entry-points." +"gui_scripts]``, pois elas seriam ambíguas perante ``[project.scripts]`` e " +"``[project.gui-scripts]``, respectivamente." -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" +"Tipo TOML_: Vetor de strings da :pep:`508` (``dependencies``) e uma tabela " +"com valores de vetores de strings da :pep:`508` (``optional-dependencies``)" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Requires-Dist ` e :ref:`Provides-Extra `" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" -msgstr "O arquivo :file:`.pypirc`" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." +msgstr "As dependências (opcionais) do projeto." -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:365 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -"Um arquivo :file:`.pypirc` permite que você defina a configuração para :term:" -"`índices de pacotes <Índice de Pacotes>` (referido aqui como " -"\"repositórios\"), para que você não precise inserir a URL, nome de usuário " -"ou senha sempre que você enviar um pacote com :ref:`twine` ou :ref:`flit`." - -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" -msgstr "O formato (originalmente definido pelo pacote :ref:`distutils`) é:" +"Para ``dependencies``, é uma chave cujo valor é um array de strings. Cada " +"string representa uma dependência do projeto e DEVE ser formatada como uma " +"string válida :pep:`508`. Cada string mapeia diretamente para um :ref:" +"`Requires-Dist `." -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:370 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -"A seção ``distutils`` define um campo ``index-servers`` que lista o nome de " -"todas as seções descrevendo um repositório." - -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" -msgstr "Cada seção descrevendo um repositório define três campos:" - -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." -msgstr "``repository``: A URL do repositório." +"Para ``optional-dependencies``, é uma tabela onde cada chave especifica um " +"extra e cujo valor é um vetor de strings. As strings dos vetores devem ser " +"strings válidas da :pep:`508`. As chaves DEVEM ser valores válidos para :ref:" +"`Provides-Extra `. Cada valor no vetor torna-" +"se assim uma entrada correspondente de :ref:`Requer-Dist ` para os metadados correspondentes de :ref:`Provides-Extra " +"`." -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." -msgstr "``username``: O nome de usuário registrado no repositório." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" +msgstr "Tipo TOML_: vetor de string" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -"``password``: A senha que será usada para autenticar o nome de usuário." +"Campo correspondente dos :ref:`metadados principais `: :ref:" +"`Dynamic `" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -"Esteja ciente de que isso armazena sua senha em texto simples. Para melhor " -"segurança, considere uma alternativa como `chaveiro`_, configurando " -"variáveis de ambiente ou fornecendo a senha na linha de comando." +"Especifica quais chaves listadas por esta PEP foram intencionalmente não " +"especificadas para que outra ferramenta possa/vai fornecer tais metadados " +"dinamicamente. Isso delineia claramente quais metadados são propositalmente " +"não especificados e espera-se que permaneçam não especificados em comparação " +"a serem fornecidos por meio de ferramentas posteriormente." -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -"Caso contrário, defina as permissões em :file:`.pypirc` para que somente " -"você possa ver ou modificá-lo. Por exemplo, no Linux ou macOS, execute:" - -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" -msgstr "Configurações comuns" +"Um backend de construção DEVE respeitar metadados especificados " +"estaticamente (o que significa que os metadados não listam a chave em " +"``dynamic``)." -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -"Esses exemplos se aplicam a :ref:`twine`. Outros projetos (por exemplo, :ref:" -"`flit`) também usam :file:`.pypirc`, mas com padrões diferentes. Consulte a " -"documentação de cada projeto para obter mais detalhes e instruções de uso." +"Um backend de construção DEVE gerar um erro se os metadados especificarem " +"``name`` em ``dynamic``." -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -"A configuração padrão do Twine imita um :file:`.pypirc` com seções de " -"repositório para PyPI e TestPyPI:" +"Se a especificação de :ref:`metadados principais ` lista um " +"campo como \"Required\", então os metadados DEVEM especificar a chave " +"estaticamente ou listá-la em ``dynamic`` (backends de construção DEVEM gerar " +"um erro, caso contrário , ou seja, não deve ser possível que uma chave " +"obrigatória não seja listada de alguma forma na tabela ``[project]``)." -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -"Twine irá adicionar configuração adicional de :file:`$HOME/.pypirc`, a linha " -"de comando e variáveis de ambiente a esta configuração padrão." +"Se a especificação de :ref:`metadados principais ` listar um " +"campo como \"Optional\", os metadados PODEM listá-lo em ``dynamic`` se a " +"expectativa for um backend de construção fornecerá os dados para a chave " +"mais tarde." -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" -msgstr "Usando um token do PyPI" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" +"Os backends de construção DEVEM levantar um erro se os metadados " +"especificarem uma chave estaticamente, além de serem listados em ``dynamic``." -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -"Para definir seu `token de API`_ para PyPI, você pode criar um :file:`$HOME/." -"pypirc` semelhante a:" +"Se os metadados não listam uma chave em ``dynamic``, então um backend de " +"construção NÃO PODE preencher os metadados necessários em nome do usuário " +"(ou seja, ``dynamic`` é a única maneira de permitir que uma ferramenta " +"preencha metadados e o usuário deve optar pelo preenchimento)." -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -"Para o :ref:`TestPyPI `, adicione a seção ``[testpypi]``, " -"usando o token de API de sua conta do TestPyPI." +"Os backends de construção DEVEM levantar um erro se os metadados " +"especificarem uma chave em ``dynamic``, mas o backend de construção não foi " +"capaz de determinar os dados para ele (omitir os dados, se determinado como " +"o valor exato, é aceitável) ." -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" -msgstr "Usando outro índice de pacotes" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -"Para configurar um repositório adicional, você precisará redefinir o campo " -"``index-servers`` para incluir o nome do repositório. Aqui está um exemplo " -"completo de um :file:`$HOME/.pypirc` para PyPI, TestPyPI e um repositório " -"privado:" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -"Em vez de usar o campo ``password``, considere salvar seus tokens de API e " -"senhas com segurança usando um `chaveiro`_ (que é instalado pelo Twine):" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "Gravando projetos instalados" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -20464,7 +20124,7 @@ msgstr "" "metadados comum permite que as ferramentas consultem, gerenciem ou " "desinstalem projetos, independentemente de como foram instalados." -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -20479,11 +20139,11 @@ msgstr "" "um formato específico para as ferramentas Python, ele ainda deve registrar o " "nome e a versão do projeto instalado." -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "Histórico e fluxo de trabalho de mudança" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 #, fuzzy msgid "" "The metadata described here was first specified in :pep:`376`, and later " @@ -20500,7 +20160,7 @@ msgstr "" "(exceto correções triviais de linguagem ou tipografia) devem ser feitas " "através do processo de PEP (veja :pep:`1`)." -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 #, fuzzy msgid "" "While this document is the normative specification, the PEPs that introduce " @@ -20511,7 +20171,7 @@ msgstr "" "introduzem alterações nele podem incluir informações adicionais, como " "justificativas e considerações de compatibilidade com versões anteriores." -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " @@ -20521,17 +20181,8 @@ msgstr "" "um diretório \"``.dist-info``\" localizado junto com os módulos e pacotes " "importáveis (comumente, o diretório ``site-packages``)." -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 #, fuzzy -#| msgid "" -#| "This directory is named as ``{name}-{version}.dist-info``, with ``name`` " -#| "and ``version`` fields corresponding to :ref:`core-metadata`. Both fields " -#| "must be normalized (see :ref:`name-normalization` and :pep:`PEP 440 " -#| "<440#normalization>` for the definition of normalization for each field " -#| "respectively), and replace dash (``-``) characters with underscore " -#| "(``_``) characters, so the ``.dist-info`` directory always has exactly " -#| "one dash (``-``) character in its stem, separating the ``name`` and " -#| "``version`` fields." msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -20551,7 +20202,7 @@ msgstr "" "tem exatamente um caractere de traço (``-``) em seu radical, separando os " "campos ``name`` e ``version``." -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -20570,18 +20221,8 @@ msgstr "" "e ``version`` usando as regras descritas acima, e as ferramentas existentes " "são encorajadas a começar a normalizar esses campos." -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 #, fuzzy -#| msgid "" -#| "The ``.dist-info`` directory's name is formatted to unambigiously " -#| "represent a distribution as a filesystem path. Tools presenting a " -#| "distribution name to a user should avoid using the normalized name, and " -#| "instead present the specified name (when needed prior to resolution to an " -#| "installed package), or read the respective fields in Core Metadata, since " -#| "values listed there are unescaped and accurately reflect the " -#| "distribution. Libraries should provide API for such tools to consume, so " -#| "tools can have access to the unnormalized name when displaying " -#| "distrubution information." msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -20603,7 +20244,7 @@ msgstr "" "possam ter acesso ao nome não normalizado ao exibir informações de " "distribuição." -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 #, fuzzy msgid "" "This ``.dist-info`` directory may contain the following files, described in " @@ -20612,29 +20253,29 @@ msgstr "" "Este diretório ``.dist-info`` pode conter esses arquivos, descritos em " "detalhes abaixo:" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "``METADATA``: contém metadados do projeto" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "``RECORD``: registra a lista de arquivos instalados." -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" "``INSTALLER``: registra o nome da ferramenta usada para instalar o projeto." -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " @@ -20644,7 +20285,7 @@ msgstr "" "omitidos a critério da ferramenta de instalação. Arquivos adicionais " "específicos do instalador podem estar presentes." -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -20656,7 +20297,7 @@ msgstr "" "`Wheel`. Esses arquivos podem ser copiados para o diretório ``.dist-info`` " "de um projeto instalado." -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -20669,11 +20310,11 @@ msgstr "" "`_ para seu significado " "original." -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "O arquivo METADATA" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." @@ -20681,7 +20322,7 @@ msgstr "" "O arquivo ``METADATA`` contém metadados conforme descrito na especificação :" "ref:`core-metadata`, versão 1.1 ou superior." -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " @@ -20691,11 +20332,11 @@ msgstr "" "metadados principais necessários não estiverem disponíveis, os instaladores " "devem relatar um erro e falhar ao instalar o projeto." -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "O arquivo RECORD" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." @@ -20703,7 +20344,7 @@ msgstr "" "O arquivo ``RECORD`` contém a lista de arquivos instalados. É um arquivo CSV " "contendo um registro (linha) por arquivo instalado." -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" @@ -20711,19 +20352,19 @@ msgstr "" "O dialeto CSV deve ser legível com o ``reader`` padrão do módulo ``csv`` do " "Python:" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "delimitador de campo: ``,`` (vírgula)," -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "caractere de aspas: ``\"`` (aspas duplas)," -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "terminador de linha: ``\\r\\n`` ou ``\\n``." -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." @@ -20731,7 +20372,7 @@ msgstr "" "Cada registro é composto de três elementos: o **caminho** do arquivo, o " "**hash** do conteúdo e seu **tamanho**." -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -20743,7 +20384,7 @@ msgstr "" "Windows, os diretórios podem ser separados por barras ou barras invertidas " "(``/`` ou ``\\``)." -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -20755,7 +20396,7 @@ msgstr "" "conteúdo do arquivo, codificado com a codificação urlsafe-base64-nopad " "(``base64.urlsafe_b64encode(digest)`` com ``=`` ao final removido)." -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." @@ -20763,7 +20404,7 @@ msgstr "" "O *tamanho* é a string vazia ou o tamanho do arquivo em bytes, como um " "inteiro de base 10." -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -20777,7 +20418,7 @@ msgstr "" "não é recomendável deixar as informações de fora, pois impede a verificação " "da integridade do projeto instalado." -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -20791,7 +20432,7 @@ msgstr "" "conteúdo do diretório ``.dist-info`` (incluindo o próprio arquivo " "``RECORD``) deve ser listado. Os diretórios não devem ser listados." -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " @@ -20802,11 +20443,11 @@ msgstr "" "todos os níveis de otimização) correspondentes aos arquivos ``.py`` " "removidos e quaisquer diretórios esvaziados pela desinstalação." -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "Aqui está um trecho de exemplo de um possível arquivo ``RECORD``::" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 #, fuzzy msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " @@ -20819,7 +20460,7 @@ msgstr "" "aplica a ferramentas que dependem de outras fontes de informação, como " "gerenciadores de pacotes do sistema em distros Linux.)" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -20829,11 +20470,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "O arquivo INSTALLER" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -20845,17 +20486,17 @@ msgstr "" "partir da linha de comando, ``INSTALLER`` deve conter o nome do comando. " "Caso contrário, deve conter uma string ASCII imprimível." -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" "O arquivo pode ser encerrado com zero ou mais caracteres de espaço em branco " "ASCII." -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "Aqui estão exemplos de dois possíveis arquivos ``INSTALLER``::" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -20867,11 +20508,11 @@ msgstr "" "``RECORD``, pode sugerir que a ferramenta nomeada em ``INSTALLER`` pode ser " "capaz de fazer a desinstalação." -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -20879,16 +20520,16 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 #, fuzzy msgid "Its detailed specification is at :ref:`entry-points`." msgstr "Sua especificação detalhada está em :ref:`direct-url`." -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "O arquivo direct_url.json" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." @@ -20897,15 +20538,15 @@ msgstr "" "partir de um requisito que especifica uma referência de URL direta " "(incluindo uma URL de VCS)." -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "Sua especificação detalhada está em :ref:`direct-url`." -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -20914,11 +20555,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -20926,14 +20567,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -20942,7 +20583,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -20959,7 +20600,6 @@ msgstr "Metadados de distribuição de pacotes" #: ../source/specifications/section-installation-metadata.rst:3 #, fuzzy -#| msgid "Package Installation Environment Metadata" msgid "Package Installation Metadata" msgstr "Metadados do ambiente de instalação de pacotes" @@ -20979,13 +20619,6 @@ msgstr "" #: ../source/specifications/simple-repository-api.rst:12 #, fuzzy -#| msgid "" -#| "The current interface for querying available package versions and " -#| "retrieving packages from an index server is defined in :pep:`503`, with " -#| "the addition of \"yank\" support (allowing a kind of file deletion) in :" -#| "pep:`592`, specifying the interface version provided by an index server " -#| "in :pep:`629`, and providing package metadata independently from a " -#| "package in :pep:`658`." msgid "" "The HTML format is defined in :pep:`503`, with the addition of \"yank\" " "support (allowing a kind of file deletion) in :pep:`592`, specifying the " @@ -21093,10 +20726,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:45 #, fuzzy -#| msgid "" -#| "Code that produces a source distribution file MUST give the file a name " -#| "that matches this specification. This includes the ``build_sdist`` hook " -#| "of a build backend." msgid "" "Code that produces a source distribution file MUST give the file a name that " "matches this specification. This includes the ``build_sdist`` hook of a :" @@ -21123,15 +20752,16 @@ msgid "Source distribution file format" msgstr "Formato de arquivo de distribuição fonte" #: ../source/specifications/source-distribution-format.rst:57 +#, fuzzy msgid "" "A ``.tar.gz`` source distribution (sdist) contains a single top-level " "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" "Uma distribuição fonte ``.tar.gz`` (sdist) contém um único diretório de " "nível superior chamado ``{name}-{version}`` (por exemplo, ``foo-1.0``), " @@ -21165,7 +20795,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:76 #, fuzzy -#| msgid "Source distribution file format" msgid "Source distribution archive features" msgstr "Formato de arquivo de distribuição fonte" @@ -21250,7 +20879,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:121 #, fuzzy -#| msgid "Generating distribution archives" msgid "When extracting *sdist* archives:" msgstr "Gerando arquivos de distribuição" @@ -21320,24 +20948,23 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "Especificadores de versão" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy -#| msgid "Specifications" msgid "Definitions" msgstr "Especificações" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -21345,7 +20972,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -21353,19 +20980,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -21373,26 +21000,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy -#| msgid "Versions" msgid "Version scheme" msgstr "Versões" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -21400,28 +21026,27 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy -#| msgid "Local version identifiers" msgid "Public version identifiers" msgstr "Identificadores de versão local" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -21429,7 +21054,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -21437,63 +21062,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -21501,11 +21126,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -21514,7 +21139,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -21524,7 +21149,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -21533,7 +21158,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -21541,25 +21166,24 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 #, fuzzy -#| msgid "Start & end with an ASCII letter or digit." msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "Começar e terminar com uma letra ou dígito ASCII." -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -21573,7 +21197,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -21581,7 +21205,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -21593,38 +21217,37 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 #, fuzzy -#| msgid "Publishing releases" msgid "Final releases" msgstr "Publicando lançamentos" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -21632,21 +21255,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "Por exemplo::" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -21654,37 +21281,36 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-releases" msgstr "Versionamento de pré-lançamento" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -21692,50 +21318,49 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy -#| msgid "zest.releaser" msgid "Post-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -21743,7 +21368,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -21751,11 +21376,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -21763,11 +21388,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -21775,20 +21400,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -21797,13 +21422,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -21813,30 +21438,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy -#| msgid "Versions" msgid "Version epochs" msgstr "Versões" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -21847,14 +21471,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -21862,24 +21486,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy -#| msgid "Normalization" msgid "Integer Normalization" msgstr "Normalização" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -21888,13 +21511,12 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release separators" msgstr "Versionamento de pré-lançamento" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -21904,13 +21526,12 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release spelling" msgstr "Versionamento de pré-lançamento" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -21920,11 +21541,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -21932,11 +21553,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -21947,13 +21568,12 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 #, fuzzy -#| msgid "Pre-release versioning" msgid "Post release spelling" msgstr "Versionamento de pré-lançamento" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -21961,11 +21581,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -21973,11 +21593,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -21987,11 +21607,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -21999,11 +21619,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -22011,13 +21631,12 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 #, fuzzy -#| msgid "Local version identifiers" msgid "Local version segments" msgstr "Identificadores de versão local" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -22025,11 +21644,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -22038,11 +21657,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -22051,13 +21670,12 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 #, fuzzy -#| msgid "Here are some examples of compliant version numbers::" msgid "Examples of compliant version schemes" msgstr "Aqui estão alguns exemplos de números de versão compatíveis::" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -22067,7 +21685,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -22075,71 +21693,70 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 #, fuzzy -#| msgid "Serial versioning" msgid "Simple \"major.minor\" versioning::" msgstr "Versionamento serial" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -22147,48 +21764,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -22199,7 +21816,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -22209,19 +21826,18 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 #, fuzzy -#| msgid "Dealing with the universal wheels" msgid "Compatibility with other version schemes" msgstr "Lidando com os wheels universais" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -22230,20 +21846,19 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 #, fuzzy -#| msgid "Serial versioning" msgid "Semantic versioning" msgstr "Versionamento serial" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -22254,7 +21869,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -22262,32 +21877,31 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 #, fuzzy -#| msgid "Date based versioning" msgid "DVCS based version labels" msgstr "Versionamento baseado em data" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -22295,32 +21909,31 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 #, fuzzy -#| msgid "Date based versioning" msgid "Olson database versioning" msgstr "Versionamento baseado em data" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -22328,60 +21941,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -22390,83 +22003,81 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 #, fuzzy -#| msgid "This means that the following names are all equivalent:" msgid "For example, the following groups of version clauses are equivalent::" msgstr "Isso significa que os seguintes nomes são todos equivalentes:" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy -#| msgid "Version" msgid "Version matching" msgstr "Versão" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -22475,7 +22086,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -22483,31 +22094,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -22515,7 +22126,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -22524,7 +22135,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -22534,14 +22145,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -22550,30 +22161,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy -#| msgid "Version Specifier" msgid "Version exclusion" msgstr "Especificador de Versão" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -22582,27 +22192,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -22612,7 +22222,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -22622,13 +22232,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=``. It is RECOMMENDED that only hashes which " -#| "are unconditionally provided by the latest version of the standard " -#| "library's ``hashlib`` module be used for source archive hashes. At time " -#| "of writing, that list consists of 'md5', 'sha1', 'sha224', 'sha256', " -#| "'sha384', and 'sha512'." msgid "" "It is RECOMMENDED that only hashes which are unconditionally provided by the " "latest version of the standard library's ``hashlib`` module be used for " @@ -22849,14 +22450,14 @@ msgstr "" "da escrita, essa lista consistia em 'md5', 'sha1', 'sha224', 'sha256', " "'sha384' e 'sha512'." -#: ../source/specifications/version-specifiers.rst:1119 +#: ../source/specifications/version-specifiers.rst:1121 msgid "" "For source archive and wheel references, an expected hash value may be " "specified by including a ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -22865,7 +22466,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -22873,7 +22474,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -22884,19 +22485,17 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy -#| msgid "For example::" msgid "Remote URL examples::" msgstr "Por exemplo::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 #, fuzzy -#| msgid "Archive URLs" msgid "File URLs" msgstr "URLs de arquivos" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -22904,7 +22503,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -22912,7 +22511,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -22924,43 +22523,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -22969,20 +22568,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -23087,7 +22686,6 @@ msgstr "" #: ../source/tutorials/creating-documentation.rst:4 #, fuzzy -#| msgid "Creating Documentation" msgid "Creating documentation" msgstr "Criando documentação" @@ -23123,16 +22721,6 @@ msgstr "" #: ../source/tutorials/installing-packages.rst:10 #, fuzzy -#| msgid "" -#| "It's important to note that the term \"package\" in this context is being " -#| "used to describe a bundle of software to be installed (i.e. as a synonym " -#| "for a :term:`distribution `). It does not to refer " -#| "to the kind of :term:`package ` that you import in your " -#| "Python source code (i.e. a container of modules). It is common in the " -#| "Python community to refer to a :term:`distribution ` using the term \"package\". Using the term \"distribution\" is " -#| "often not preferred, because it can easily be confused with a Linux " -#| "distribution, or another larger software distribution like Python itself." msgid "" "It's important to note that the term \"package\" in this context is being " "used to describe a bundle of software to be installed (i.e. as a synonym for " @@ -23481,10 +23069,6 @@ msgstr "" #: ../source/tutorials/installing-packages.rst:276 #, fuzzy -#| msgid "" -#| "In both of the above cases, Windows users should _not_ use the :command:" -#| "`source` command, but should rather run the :command:`activate` script " -#| "directly from the command shell like so:" msgid "" "In both of the above cases, Windows users should *not* use the :command:" "`source` command, but should rather run the :command:`activate` script " @@ -23527,15 +23111,6 @@ msgid "Installing from PyPI" msgstr "Instalando a partir do PyPI" #: ../source/tutorials/installing-packages.rst:303 -#, fuzzy -#| msgid "" -#| "The most common usage of :ref:`pip` is to install from the :term:`Python " -#| "Package Index ` using a :term:`requirement " -#| "specifier `. Generally speaking, a requirement " -#| "specifier is composed of a project name followed by an optional :term:" -#| "`version specifier `. :pep:`440` contains a :pep:" -#| "`full specification <440#version-specifiers>` of the currently supported " -#| "specifiers. Below are some examples." msgid "" "The most common usage of :ref:`pip` is to install from the :term:`Python " "Package Index ` using a :term:`requirement " @@ -23549,9 +23124,10 @@ msgstr "" "Index ` usando um :term:`especificador de " "requisitos `. De modo geral, um especificador " "de requisitos é composto de um nome de projeto seguido por um :term:" -"`especificador de versão ` opcional . :pep:`440` " -"contém uma :pep:`especificação completa <440#version-specifiers>` dos " -"especificadores suportados atualmente. Abaixo estão alguns exemplos." +"`especificador de versão ` opcional . A descrição " +"completa dos especificadores suportados podem ser encontrados na :ref:" +"`especificação de especificadores de versão `. Abaixo " +"estão alguns exemplos." #: ../source/tutorials/installing-packages.rst:311 msgid "To install the latest version of \"SomeProject\":" @@ -23567,9 +23143,6 @@ msgstr "Para instalar maior ou igual a uma versão e menor que outra:" #: ../source/tutorials/installing-packages.rst:354 #, fuzzy -#| msgid "" -#| "To install a version that's :pep:`\"compatible\" <440#compatible-" -#| "release>` with a certain version: [4]_" msgid "" "To install a version that's :ref:`compatible ` with a certain version: [4]_" @@ -24087,11 +23660,6 @@ msgstr "" #: ../source/tutorials/managing-dependencies.rst:170 #, fuzzy -#| msgid "" -#| "`PDM `_ for a modern Python package " -#| "management tool supporting :pep:`582` (replacing virtual environments " -#| "with ``__pypackages__`` directory for package installation) and relying " -#| "on standards such as :pep:`517` and :pep:`621`." msgid "" "`PDM `_ for a modern Python package " "management relying on standards such as :pep:`517` and :pep:`621`." @@ -24199,9 +23767,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:57 #, fuzzy -#| msgid "" -#| ":file:`__init__.py` is required to import the directory as a package, and " -#| "should be empty." msgid "" ":file:`__init__.py` is recommended to import the directory as a regular " "package, even if as is our case for this tutorial that file is empty " @@ -24279,15 +23844,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:120 #, fuzzy -#| msgid "" -#| ":file:`pyproject.toml` tells \"frontend\" build tools like :ref:`pip` " -#| "and :ref:`build` what \"backend\" tool to use to create :term:" -#| "`distribution packages ` for your project. You can " -#| "choose from a number of backends; this tutorial uses :ref:`Hatchling " -#| "` by default, but it will work identically with :ref:" -#| "`setuptools`, :ref:`Flit `, :ref:`PDM `, and others that " -#| "support the ``[project]`` table for :ref:`metadata `." msgid "" "You can choose from a number of backends; this tutorial uses :ref:`Hatchling " "` by default, but it will work identically with :ref:`setuptools`, :" @@ -24317,11 +23873,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:132 #, fuzzy -#| msgid "" -#| ":file:`pyproject.toml` tells build tools (like :ref:`pip` and :ref:" -#| "`build`) what is required to build your project. This tutorial uses :ref:" -#| "`setuptools`, so open :file:`pyproject.toml` and enter the following " -#| "content:" msgid "" "The :file:`pyproject.toml` tells :term:`build frontend ` " "tools like :ref:`pip` and :ref:`build` which backend to use for your " @@ -24345,9 +23896,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:177 #, fuzzy -#| msgid "" -#| "``build-backend`` is the name of the Python object that frontends will " -#| "use to perform the build." msgid "" "The ``build-backend`` key is the name of the Python object that frontends " "will use to perform the build." @@ -24404,11 +23952,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:227 #, fuzzy -#| msgid "" -#| "``version`` is the package version. See the :ref:`version specifier " -#| "specification ` for more details on versions. Some " -#| "build backends allow it to be specified another way, such as from a file " -#| "or a git tag." msgid "" "``version`` is the package version. (Some build backends allow it to be " "specified another way, such as from a file or Git tag.)" @@ -24434,12 +23977,6 @@ msgstr "``description`` é um resumo curto do pacote contendo apenas uma frase." #: ../source/tutorials/packaging-projects.rst:233 #, fuzzy -#| msgid "" -#| "``readme`` is a path to a file containing a detailed description of the " -#| "package. This is shown on the package detail page on PyPI. In this case, " -#| "the description is loaded from :file:`README.md` (which is a common " -#| "pattern). There also is a more advanced table form described in the :ref:" -#| "`project metadata specification `." msgid "" "``readme`` is a path to a file containing a detailed description of the " "package. This is shown on the package detail page on PyPI. In this case, the " @@ -24455,10 +23992,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:238 #, fuzzy -#| msgid "" -#| "``requires-python`` gives the versions of Python supported by your " -#| "project. Installers like :ref:`pip` will look back through older versions " -#| "of packages until it finds one that has a matching Python version." msgid "" "``requires-python`` gives the versions of Python supported by your project. " "An installer like :ref:`pip` will look back through older versions of " @@ -24497,12 +24030,6 @@ msgstr "" #: ../source/tutorials/packaging-projects.rst:251 #, fuzzy -#| msgid "" -#| "See the :ref:`project metadata specification ` for details on these and other fields that can be defined in " -#| "the ``[project]`` table. Other common fields are ``keywords`` to improve " -#| "discoverability and the ``dependencies`` that are required to install " -#| "your package." msgid "" "See the :ref:`pyproject.toml guide ` for details on " "these and other fields that can be defined in the ``[project]`` table. Other " @@ -24842,7 +24369,21 @@ msgstr "" "Neste ponto, se você quiser ler mais sobre o empacotamento de bibliotecas " "Python, aqui estão algumas coisas que você pode fazer:" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:536 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:539 msgid "" "Consider packaging tools that provide a single command-line interface for " "project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" @@ -24852,23 +24393,11 @@ msgstr "" "de linha de comando para gerenciamento e empacotamento de projetos, como :" "ref:`hatch`, :ref:`flit`, :ref:`pdm` e :ref:`poetry`." -#: ../source/tutorials/packaging-projects.rst:538 -msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." -msgstr "" -"Leia a :pep:`517` e a :pep:`518` para um informações e detalhes sobre a " -"configuração de ferramenta de construção." - -#: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "Leia sobre :doc:`/guides/packaging-binary-extensions`." - -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "Este é o nome do seu projeto, determinando como ele está listado no :term:" +#~ "`PyPI `. Conforme :pep:`508`, nomes de " +#~ "projetos válidos devem:" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "Começar e terminar com uma letra ou dígito ASCII." + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "Esta é a versão atual do seu projeto, permitindo que seus usuários " +#~ "determinem se têm ou não a versão mais recente e indiquem em quais " +#~ "versões específicas eles testaram seu próprio software." + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "As versões são exibidas em :term:`PyPI ` " +#~ "para cada lançamento se você publicar seu projeto." + +#~ msgid "" +#~ "If the project code itself needs run-time access to the version, the " +#~ "simplest way is to keep the version in both :file:`setup.py` and your " +#~ "code. If you'd rather not duplicate the value, there are a few ways to " +#~ "manage this. See the \":ref:`Single sourcing the version`\" Advanced " +#~ "Topics section." +#~ msgstr "" +#~ "Se o código do projeto em si precisa de acesso em tempo de execução para " +#~ "a versão, a maneira mais simples é manter a versão em :file:`setup.py` e " +#~ "seu código. Se você preferir não duplicar o valor, existem algumas " +#~ "maneiras de gerenciar isso. Consulte a seção de tópicos avançados \":ref:" +#~ "`Fonte única da versão `\"." + +#~ msgid "Give a short and long description for your project." +#~ msgstr "Da uma descrição curta e longa para seu projeto." + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "Esses valores serão exibidos no :term:`PyPI ` se você publicar seu projeto. No ``pypi.org``, a interface do " +#~ "usuário exibe ``description`` no banner cinza e ``long_description`` na " +#~ "seção chamada \"Descrição do Projeto\"." + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description`` também é exibido em listas de projetos. Por exemplo, ele " +#~ "é visível nas páginas de resultados de pesquisa, como https://pypi.org/" +#~ "search/?q=jupyter, nas listas da página inicial de projetos populares e " +#~ "novos lançamentos e na lista de projetos que você mantém no perfil de sua " +#~ "conta (como https://pypi.org/user/jaraco/)." + +#~ msgid "" +#~ "A :ref:`content type ` can be " +#~ "specified with the ``long_description_content_type`` argument, which can " +#~ "be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, " +#~ "corresponding to no formatting, `reStructuredText (reST) `_, and the GitHub-flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "Um :ref:`tipo de conteúdo ` pode " +#~ "ser especificado com o argumento ``long_description_content_type``, que " +#~ "pode ser um de ``text/plain``, ``text/x-rst`` ou ``text/markdown``, " +#~ "correspondendo a nenhuma formatação, `reStructuredText (reST) `_, e o dialeto Markdown com sabor do GitHub de `Markdown `_ respectivamente." + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "Fornece o URL da página inicial do seu projeto." + +#, fuzzy +#~ msgid "``author``" +#~ msgstr "author" + +#~ msgid "Provide details about the author." +#~ msgstr "Fornece detalhes sobre o autor." + +#~ msgid "" +#~ "The ``license`` argument doesn't have to indicate the license under which " +#~ "your package is being released, although you may optionally do so if you " +#~ "want. If you're using a standard, well-known license, then your main " +#~ "indication can and should be via the ``classifiers`` argument. " +#~ "Classifiers exist for all major open-source licenses." +#~ msgstr "" +#~ "O argumento ``license`` não precisa indicar a licença sob a qual seu " +#~ "pacote está sendo lançado, embora você possa opcionalmente fazer isso se " +#~ "desejar. Se você estiver usando uma licença padrão bem conhecida, sua " +#~ "indicação principal pode e deve ser por meio do argumento " +#~ "``classifiers``. Existem classificadores para todas as principais " +#~ "licenças de código aberto." + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "Fornece uma lista de classificadores que categorizam seu projeto. Para " +#~ "obter uma lista completa, consulte https://pypi.org/classifiers/." + +#~ msgid "List keywords that describe your project." +#~ msgstr "Lista as palavras-chave que descrevem seu projeto." + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "project_urls" + +#~ msgid "" +#~ "List additional relevant URLs about your project. This is the place to " +#~ "link to bug trackers, source repositories, or where to support package " +#~ "development. The string of the key is the exact text that will be " +#~ "displayed on PyPI." +#~ msgstr "" +#~ "Lista URLs relevantes adicionais sobre seu projeto. Este é o lugar para " +#~ "se conectar a rastreadores de bugs, repositórios fontes ou onde oferecer " +#~ "suporte ao desenvolvimento de pacotes. A string da chave é o texto exato " +#~ "que será exibido no PyPI." + +#, fuzzy +#~ msgid "``python_requires``" +#~ msgstr "python_requires" + +#~ msgid "" +#~ "If your project only runs on certain Python versions, setting the " +#~ "``python_requires`` argument to the appropriate :pep:`440` version " +#~ "specifier string will prevent :ref:`pip` from installing the project on " +#~ "other Python versions. For example, if your package is for Python 3+ " +#~ "only, write::" +#~ msgstr "" +#~ "Se o seu projeto só funciona em certas versões do Python, definir o " +#~ "argumento ``python_requires`` para a string apropriada especificadora de " +#~ "versão da :pep:`440` impedirá :ref:`pip` de instalar o projeto em outras " +#~ "versões do Python. Por exemplo, se seu pacote for apenas para Python 3+, " +#~ "escreva::" + +#~ msgid "" +#~ "If your package is for Python 2.6, 2.7, and all versions of Python 3 " +#~ "starting with 3.3, write::" +#~ msgstr "" +#~ "Se o seu pacote for para Python 2.6, 2.7 e todas as versões do Python 3 " +#~ "começando com 3.3, escreva::" + +#~ msgid "And so on." +#~ msgstr "E por aí vai." + +#~ msgid "" +#~ "Support for this feature is relatively recent. Your project's source " +#~ "distributions and wheels (see :ref:`Packaging Your Project`) must be " +#~ "built using at least version 24.2.0 of :ref:`setuptools` in order for the " +#~ "``python_requires`` argument to be recognized and the appropriate " +#~ "metadata generated." +#~ msgstr "" +#~ "O suporte para esse recurso é relativamente recente. As distribuições de " +#~ "código-fonte e wheels do seu projeto (veja :ref:`Empacotando seu projeto " +#~ "`) devem ser construídas usando pelo menos a " +#~ "versão 24.2.0 do :ref:`setuptools` para que o argumento " +#~ "``python_requires`` seja reconhecido e os metadados apropriados gerados." + +#~ msgid "" +#~ "In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " +#~ "``python_requires`` metadata. Users with earlier versions of pip will be " +#~ "able to download & install projects on any Python version regardless of " +#~ "the projects' ``python_requires`` values." +#~ msgstr "" +#~ "Além disso, apenas as versões 9.0.0 e superiores do :ref:`pip` reconhecem " +#~ "os metadados de ``python_requires``. Usuários com versões anteriores do " +#~ "pip serão capazes de baixar e instalar projetos em qualquer versão do " +#~ "Python, independentemente dos valores de ``python_requires`` dos projetos." + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "Use this keyword to specify any plugins that your project provides for " +#~ "any named entry points that may be defined by your project or others that " +#~ "you depend on." +#~ msgstr "" +#~ "Use esta palavra-chave para especificar quaisquer plugins que seu projeto " +#~ "fornece para quaisquer pontos de entrada nomeados que podem ser definidos " +#~ "por seu projeto ou outros dos quais você depende." + +#~ msgid "" +#~ "For more information, see the section on :ref:`Advertising Behavior " +#~ "` from the :ref:" +#~ "`setuptools` docs." +#~ msgstr "" +#~ "Para obter mais informações, consulte a seção sobre :ref:`Comportamento " +#~ "de Publicidade ` da " +#~ "documentação do :ref:`setuptools`." + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "" +#~ "O ponto de entrada mais comumente usado é \"console_scripts\" (veja " +#~ "abaixo)." + +#, fuzzy +#~ msgid "``console_scripts``" +#~ msgstr "console_scripts" + +#~ msgid "" +#~ "Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can " +#~ "then let the toolchain handle the work of turning these interfaces into " +#~ "actual scripts [2]_. The scripts will be generated during the install of " +#~ "your :term:`distribution `." +#~ msgstr "" +#~ "Use :ref:`pontos de entrada ` de ``console_script`` para registrar suas interfaces de script. " +#~ "Você pode então deixar o conjunto de ferramentas lidar com o trabalho de " +#~ "transformar essas interfaces em scripts reais [2]_. Os scripts serão " +#~ "gerados durante a instalação do seu :term:`distribuição `." + +#~ msgid "" +#~ "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." +#~ msgstr "" +#~ "Para mais informações, veja :doc:`Entry Points ` (pontos de entrada, em português) da :doc:`documentação do " +#~ "setuptools `." + +#~ msgid "" +#~ "Specifically, the \"console_script\" approach generates ``.exe`` files on " +#~ "Windows, which are necessary because the OS special-cases ``.exe`` files. " +#~ "Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher " +#~ "for Windows <397>` allow scripts to be used in many cases, but not all." +#~ msgstr "" +#~ "Especificamente, a abordagem \"console_script\" gera arquivos ``.exe`` no " +#~ "Windows, que são necessários por causa dos arquivos ``.exe`` de casos " +#~ "especiais do sistema operacional. Recursos de execução de script como " +#~ "``PATHEXT`` e o :pep:`Inicializador do Python para Windows <397>` " +#~ "permitem que scripts sejam usados em muitos casos, mas não em todos." + +#~ msgid "" +#~ "The binary distribution format (:term:`wheel `) was originally " +#~ "defined in :pep:`427`. The current version of the specification is here." +#~ msgstr "" +#~ "O formato de distribuição binária (:term:`wheel `) foi " +#~ "originalmente definido na :pep:`427`. A versão atual da especificação " +#~ "está aqui." + +#~ msgid "Abstract" +#~ msgstr "Abstrato" + +#~ msgid "" +#~ "This PEP describes a built-package format for Python called \"wheel\"." +#~ msgstr "" +#~ "Esta PEP descreve um formato de pacote construído para Python chamado " +#~ "\"wheel\"." + +#~ msgid "PEP Acceptance" +#~ msgstr "Aceitação da PEP" + +#~ msgid "" +#~ "This PEP was accepted, and the defined wheel version updated to 1.0, by " +#~ "Nick Coghlan on 16th February, 2013 [1]_" +#~ msgstr "" +#~ "Esta PEP foi aceita, e a versão do wheel definida foi atualizada para " +#~ "1.0, por Nick Coghlan em 16 de fevereiro de 2013 [1]_" + +#~ msgid "Rationale" +#~ msgstr "Justificativa" + +#~ msgid "" +#~ "Python needs a package format that is easier to install than sdist. " +#~ "Python's sdist packages are defined by and require the distutils and " +#~ "setuptools build systems, running arbitrary code to build-and-install, " +#~ "and re-compile, code just so it can be installed into a new virtualenv. " +#~ "This system of conflating build-install is slow, hard to maintain, and " +#~ "hinders innovation in both build systems and installers." +#~ msgstr "" +#~ "Python precisa de um formato de pacote mais fácil de instalar do que " +#~ "sdist. Os pacotes sdist do Python são definidos e requerem os sistemas de " +#~ "construção distutils e setuptools, executando código arbitrário para " +#~ "construir e instalar e recompilar o código apenas para que possa ser " +#~ "instalado em um novo virtualenv. Este sistema de combinação entre " +#~ "construção e instalação é lento, difícil de manter e impede a inovação " +#~ "tanto nos sistemas de construção quanto nos instaladores." + +#~ msgid "" +#~ "Wheel attempts to remedy these problems by providing a simpler interface " +#~ "between the build system and the installer. The wheel binary package " +#~ "format frees installers from having to know about the build system, saves " +#~ "time by amortizing compile time over many installations, and removes the " +#~ "need to install a build system in the target environment." +#~ msgstr "" +#~ "O wheel tenta remediar esses problemas fornecendo uma interface mais " +#~ "simples entre o sistema de compilação e o instalador. O formato do pacote " +#~ "binário wheel libera os instaladores de ter que saber sobre o sistema de " +#~ "compilação, economiza tempo amortizando o tempo de compilação em muitas " +#~ "instalações e elimina a necessidade de instalar um sistema de compilação " +#~ "no ambiente de destino." + +#~ msgid "Comparison to .egg" +#~ msgstr "Comparação com .egg" + +#~ msgid "" +#~ "Wheel is an installation format; egg is importable. Wheel archives do " +#~ "not need to include .pyc and are less tied to a specific Python version " +#~ "or implementation. Wheel can install (pure Python) packages built with " +#~ "previous versions of Python so you don't always have to wait for the " +#~ "packager to catch up." +#~ msgstr "" +#~ "Wheel é um formato de instalação; ovo é importável. Os arquivos wheel não " +#~ "precisam incluir .pyc e estão menos vinculados a uma versão ou " +#~ "implementação específica do Python. O Wheel pode instalar pacotes (puro " +#~ "Python) construídos com versões anteriores do Python, portanto, você nem " +#~ "sempre precisa esperar que o empacotador os atualize." + +#~ msgid "" +#~ "Wheel uses .dist-info directories; egg uses .egg-info. Wheel is " +#~ "compatible with the new world of Python packaging and the new concepts it " +#~ "brings." +#~ msgstr "" +#~ "O Wheel usa diretórios .dist-info; egg usa .egg-info. Wheel é compatível " +#~ "com o novo mundo da empacotamento de Python e os novos conceitos que ele " +#~ "traz." + +#~ msgid "" +#~ "Wheel has a richer file naming convention for today's multi-" +#~ "implementation world. A single wheel archive can indicate its " +#~ "compatibility with a number of Python language versions and " +#~ "implementations, ABIs, and system architectures. Historically the ABI " +#~ "has been specific to a CPython release, wheel is ready for the stable ABI." +#~ msgstr "" +#~ "O Wheel tem uma convenção de nomenclatura de arquivo mais rica para o " +#~ "mundo de múltiplas implementações de hoje. Um único arquivo de wheel pode " +#~ "indicar sua compatibilidade com várias versões e implementações de " +#~ "linguagem Python, ABIs e arquiteturas de sistema. Historicamente, a ABI " +#~ "tem sido específica para uma versão do CPython, o wheel estando pronto " +#~ "para a ABI estável." + +#~ msgid "" +#~ "Wheel is lossless. The first wheel implementation bdist_wheel always " +#~ "generates egg-info, and then converts it to a .whl. It is also possible " +#~ "to convert existing eggs and bdist_wininst distributions." +#~ msgstr "" +#~ "O wheel não causa perdas. A implementação do primeiro wheel, bdist_wheel, " +#~ "sempre gera egg-info e, então, as converte em .whl. Também é possível " +#~ "converter eggs existentes e distribuições de bdist_wininst." + +#~ msgid "" +#~ "Wheel is versioned. Every wheel file contains the version of the wheel " +#~ "specification and the implementation that packaged it. Hopefully the next " +#~ "migration can simply be to Wheel 2.0." +#~ msgstr "" +#~ "Wheel é versionado. Cada arquivo wheel contém a versão da especificação " +#~ "wheel e a implementação que a empacotou. Esperançosamente, a próxima " +#~ "migração pode ser simplesmente para Wheel 2.0." + +#~ msgid "Wheel is a reference to the other Python." +#~ msgstr "Wheel é uma referência a outro Python." + +#~ msgid "Changes" +#~ msgstr "Alterações" + +#~ msgid "Since :pep:`427`, this specification has changed as follows:" +#~ msgstr "Desde a :pep:`427`, esta especificação mudou da seguinte forma:" + +#~ msgid "" +#~ "PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" +#~ msgstr "" +#~ "Aceitação da PEP (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" + +#~ msgid "This document has been placed into the public domain." +#~ msgstr "Este documento foi colocado em domínio público." + +#~ msgid "``python -m twine check``" +#~ msgstr "``python -m twine check``" + +#~ msgid "``python -m twine register``" +#~ msgstr "``python -m twine register``" + +#~ msgid "``python -m twine upload``" +#~ msgstr "``python -m twine upload``" + +#~ msgid "``python -m setuptools-scm``" +#~ msgstr "``python -m setuptools-scm``" + +#~ msgid "" +#~ "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); " +#~ "see :doc:`Declaring project metadata ` for more detail" +#~ msgstr "" +#~ "uma tabela ``[project]`` contendo os :doc:`Metadados Principais ` (nome, versão, autor e assim por diante) " +#~ "do projeto; veja :doc:`Declarando os metadados do projeto ` para mais detalhes" + +#~ msgid "a ``[tool]`` table containing tool-specific configuration options" +#~ msgstr "" +#~ "uma tabela ``[tool]`` contendo opções de configuração específicas da " +#~ "ferramenta" + +#~ msgid "" +#~ "A `content type `_ can be specified with the " +#~ "``long_description_content_type`` argument, which can be one of ``text/" +#~ "plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " +#~ "formatting, `reStructuredText (reST) `_, and the GitHub-" +#~ "flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "Um `tipo de conteúdo `_ pode ser especificado com " +#~ "o argumento ``long_description_content_type``, que pode ser um de ``text/" +#~ "plain``, ``text/x-rst`` ou ``text/markdown``, correspondendo a nenhuma " +#~ "formatação, `reStructuredText (reST) `_, e o dialeto " +#~ "Markdown com sabor do GitHub de `Markdown `_ respectivamente." + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "Você pode aprender mais sobre pipx em https://pypa.github.io/pipx/." + +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr ":ref:`declaring-build-dependencies`" + +#~ msgid "" +#~ "Read :ref:`declaring-project-metadata` for the full specification of the " +#~ "content allowed in the ``[project]`` table." +#~ msgstr "" +#~ "Leia :ref:`declaring-project-metadata` para a especificação completa do " +#~ "conteúdo permitido na tabela ``[project]``." + +#~ msgid ":ref:`declaring-project-metadata`" +#~ msgstr ":ref:`declaring-project-metadata`" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`Documentação `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `GitHub `__" +#~ msgstr "" +#~ ":doc:`Documentação ` | `Issues `__ | `GitHub `__" + +#~ msgid "" +#~ "trove-classifiers is the canonical source for `classifiers on PyPI " +#~ "`_, which project maintainers use to " +#~ "`systematically describe their projects `_ so that users " +#~ "can better find projects that match their needs on the PyPI." +#~ msgstr "" +#~ "trove-classifiers é a fonte canônica para `classificadores no PyPI " +#~ "`_, que os mantenedores de projetos usam " +#~ "para `descrever sistematicamente seus projetos `_ para que os " +#~ "usuários possam encontrar melhor os projetos que correspondem às suas " +#~ "necessidades no PyPI." + +#~ msgid "Declaring build system dependencies" +#~ msgstr "Declarando dependências do sistema de construção" + +#, fuzzy +#~ msgid "" +#~ "The ``pyproject.toml`` file is written in `TOML `_. " +#~ "Among other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " +#~ "installed in order to run the project's build system successfully." +#~ msgstr "" +#~ "`pyproject.toml` é um formato de arquivo independente do sistema de " +#~ "construção definido na :pep:`518` que os projetos podem fornecer para " +#~ "declarar quaisquer dependências de nível Python que devem ser instaladas " +#~ "para executar o sistema de construção do projeto com sucesso." + +#~ msgid "Declaring project metadata" +#~ msgstr "Declarando os metadados do projeto" + +#~ msgid "" +#~ ":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " +#~ "consume. It defines the following specification as the canonical source " +#~ "for the format used." +#~ msgstr "" +#~ "A :pep:`621` especifica como escrever :ref:`metadados principais ` de um projeto em um arquivo ``pyproject.toml`` para " +#~ "ferramentas relacionadas ao empacotamento consumirem. Ele define a " +#~ "seguinte especificação como a fonte canônica para o formato usado." + +#, fuzzy +#~ msgid "" +#~ "The keys defined in this specification MUST be in a table named " +#~ "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " +#~ "which are not defined by this specification. For tools wishing to store " +#~ "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " +#~ "table as defined in the :ref:`build dependency declaration specification " +#~ "`. The lack of a ``[project]`` table " +#~ "implicitly means the :term:`build backend ` will " +#~ "dynamically provide all keys." +#~ msgstr "" +#~ "As chaves definidas nesta especificação DEVEM estar em uma tabela chamada " +#~ "``[project]`` no arquivo ``pyproject.toml``. Nenhuma ferramenta pode " +#~ "adicionar chaves a esta tabela que não sejam definidas por esta " +#~ "especificação. Para ferramentas que desejam armazenar suas próprias " +#~ "configurações em ``pyproject.toml``, elas podem usar a tabela ``[tool]`` " +#~ "conforme definido na :ref:`especificação da declaração de dependências de " +#~ "construção `. A falta de uma tabela " +#~ "``[project]`` implicitamente significa que o backend da construção " +#~ "fornecerá dinamicamente todas as chaves." + +#~ msgid "" +#~ "A ``.tar.gz`` source distribution (sdist) contains a single top-level " +#~ "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " +#~ "source files of the package. The name and version MUST match the metadata " +#~ "stored in the file. This directory must also contain a :file:`pyproject." +#~ "toml` in the format defined in :ref:`declaring-build-dependencies`, and a " +#~ "``PKG-INFO`` file containing metadata in the format described in the :ref:" +#~ "`core-metadata` specification. The metadata MUST conform to at least " +#~ "version 2.2 of the metadata specification." +#~ msgstr "" +#~ "Uma distribuição fonte ``.tar.gz`` (sdist) contém um único diretório de " +#~ "nível superior chamado ``{name}-{version}`` (por exemplo, ``foo-1.0``), " +#~ "contendo os arquivos fonte do pacote. O nome e a versão DEVEM " +#~ "corresponder aos metadados armazenados no arquivo. Este diretório também " +#~ "deve conter um :file:`pyproject.toml` no formato definido em :ref:" +#~ "`declaring-build-dependencies` e um arquivo ``PKG-INFO`` contendo " +#~ "metadados no formato descrito na especificação :ref:`core-metadata`. Os " +#~ "metadados DEVEM estar em conformidade com pelo menos a versão 2.2 da " +#~ "especificação de metadados." + +#~ msgid "" +#~ "Read :pep:`517` and :pep:`518` for background and details on build tool " +#~ "configuration." +#~ msgstr "" +#~ "Leia a :pep:`517` e a :pep:`518` para um informações e detalhes sobre a " +#~ "configuração de ferramenta de construção." + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "Leia sobre :doc:`/guides/packaging-binary-extensions`." + #, fuzzy -#~| msgid "Tool recommendations" #~ msgid "Current recommendation" #~ msgstr "Recomendações de ferramentas" @@ -25526,12 +25616,6 @@ msgstr "" #~ msgstr "Então, adicione o seguinte sob a seção ``build-n-publish``:" #, fuzzy -#~| msgid "" -#~| "You can use any other method for building distributions as long as it " -#~| "produces ready-to-upload artifacts saved into the ``dist/`` folder. You " -#~| "can even use ``actions/upload-artifact`` and ``actions/download-" -#~| "artifact`` to tranfer files between jobs or make them accessable for " -#~| "download from the web CI interface." #~ msgid "" #~ "You can use any other method for building distributions as long as it " #~ "produces ready-to-upload artifacts saved into the ``dist/`` folder. You " diff --git a/locales/ro/LC_MESSAGES/messages.po b/locales/ro/LC_MESSAGES/messages.po index eeb3ef953..e31319c21 100644 --- a/locales/ro/LC_MESSAGES/messages.po +++ b/locales/ro/LC_MESSAGES/messages.po @@ -6,7 +6,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" "PO-Revision-Date: 2021-08-20 01:32+0000\n" "Last-Translator: GUILHERME FERNANDES NETO \n" "Language-Team: Romanian `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -896,7 +1033,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1033,145 +1170,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1179,46 +1323,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1226,26 +1370,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1562,24 +1706,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1588,22 +1736,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1611,7 +1759,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1620,43 +1768,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1747,14 +1895,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1762,11 +1911,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1775,11 +1924,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1788,67 +1937,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "Pe Indexul Proiectului" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1857,7 +2007,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1865,7 +2015,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1873,21 +2023,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Modul Pur" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1897,48 +2047,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1946,11 +2096,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1959,17 +2109,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "Specificator Cerință" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1985,12 +2133,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2149,7 +2297,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2218,14 +2366,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2581,8 +2729,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2757,6 +2904,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2765,14 +2920,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2780,36 +2935,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2830,14 +2985,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2877,11 +3032,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2889,7 +3044,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2897,16 +3052,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2916,256 +3071,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3175,78 +3142,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3255,24 +3183,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3281,7 +3209,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3293,13 +3221,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3307,12 +3235,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3320,69 +3248,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3390,42 +3277,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3433,58 +3320,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3492,44 +3379,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3539,17 +3426,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3558,13 +3445,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3574,7 +3461,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3582,21 +3469,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3605,22 +3492,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3628,23 +3515,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3653,11 +3540,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3665,95 +3552,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3761,7 +3648,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3769,7 +3656,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3778,7 +3665,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3788,78 +3675,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3867,7 +3754,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3875,14 +3762,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3996,96 +3875,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4100,9 +3970,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4384,7 +4254,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4489,6 +4359,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4517,7 +4388,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4693,7 +4564,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4752,33 +4623,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4786,146 +4657,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4933,108 +4804,108 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy #| msgid "Requirement Specifier" msgid "Using a requirements file" msgstr "Specificator Cerință" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5483,13 +5354,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5559,7 +5429,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5598,11 +5468,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6219,11 +6089,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6232,19 +6102,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6255,17 +6125,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6273,17 +6143,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6291,7 +6161,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6299,7 +6169,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6308,27 +6178,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6336,11 +6206,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6348,13 +6218,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6362,11 +6232,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6375,21 +6245,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6397,17 +6267,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6419,19 +6289,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6440,13 +6310,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6740,44 +6610,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6785,39 +6663,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6826,52 +6704,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7624,8 +7502,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7742,89 +7620,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7832,129 +7747,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8389,8 +8355,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8401,9 +8367,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8462,13 +8427,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8481,18 +8445,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8501,18 +8465,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8523,42 +8487,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8567,22 +8531,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8590,15 +8554,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8607,14 +8571,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8627,17 +8591,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8645,17 +8609,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8667,17 +8631,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8688,34 +8652,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8723,44 +8687,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8769,18 +8733,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8791,17 +8755,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8809,17 +8773,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8829,17 +8793,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8849,17 +8813,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8869,18 +8833,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8891,18 +8855,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8930,7 +8894,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8949,24 +8913,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8974,21 +8938,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8996,17 +8960,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10379,25 +10343,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10408,86 +10364,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10496,35 +10419,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10532,32 +10455,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10565,41 +10488,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10608,14 +10531,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10623,7 +10546,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10631,33 +10554,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10665,25 +10588,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10694,63 +10617,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10758,71 +10681,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10830,28 +10753,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10860,22 +10783,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10883,29 +10806,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10915,7 +10838,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10923,25 +10846,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10949,99 +10872,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11050,38 +10927,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11089,7 +10966,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11097,18 +10974,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11117,7 +10994,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11128,7 +11005,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11146,7 +11023,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11155,70 +11032,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11320,41 +11194,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11362,20 +11236,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11383,27 +11257,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11411,19 +11297,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11431,7 +11317,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11439,7 +11325,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11447,31 +11333,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11585,91 +11471,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11679,11 +11565,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11691,43 +11577,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11735,64 +11621,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11800,13 +11686,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11814,36 +11700,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11852,13 +11738,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11866,20 +11752,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11887,7 +11773,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11897,11 +11783,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11909,7 +11795,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11919,18 +11805,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11939,7 +11825,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11950,63 +11836,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12017,33 +11903,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12052,3347 +11938,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15400,7 +15281,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15409,11 +15290,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15424,21 +15305,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15450,7 +15331,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15461,7 +15342,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15473,41 +15354,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15515,7 +15396,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15523,58 +15404,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15582,7 +15463,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15590,13 +15471,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15605,7 +15486,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15614,18 +15495,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15633,7 +15514,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15643,11 +15524,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15655,15 +15536,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15671,11 +15552,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15683,29 +15564,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15714,11 +15595,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15726,14 +15607,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15742,7 +15623,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15876,10 +15757,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16049,22 +15930,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16072,7 +15953,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16080,19 +15961,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16100,24 +15981,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16125,26 +16006,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16152,7 +16033,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16160,63 +16041,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16224,11 +16105,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16237,7 +16118,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16247,7 +16128,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16256,7 +16137,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16264,23 +16145,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16294,7 +16175,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16302,7 +16183,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16314,36 +16195,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16351,21 +16232,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16373,35 +16258,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16409,48 +16294,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16458,7 +16343,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16466,11 +16351,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16478,11 +16363,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16490,20 +16375,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16512,13 +16397,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16528,28 +16413,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16560,14 +16445,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16575,22 +16460,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16599,11 +16484,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16613,11 +16498,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16627,11 +16512,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16639,11 +16524,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16654,11 +16539,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16666,11 +16551,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16678,11 +16563,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16692,11 +16577,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16704,11 +16589,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16716,11 +16601,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16728,11 +16613,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16741,11 +16626,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16754,11 +16639,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16768,7 +16653,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16776,69 +16661,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16846,48 +16731,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16898,7 +16783,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16908,17 +16793,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16927,18 +16812,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16949,7 +16834,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16957,30 +16842,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16988,30 +16873,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17019,60 +16904,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17081,79 +16966,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17162,7 +17047,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17170,31 +17055,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17202,7 +17087,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17211,7 +17096,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17221,14 +17106,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17237,28 +17122,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17267,27 +17152,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17297,7 +17182,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17307,13 +17192,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17532,7 +17417,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17540,7 +17425,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17551,15 +17436,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17567,7 +17452,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17575,7 +17460,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17587,43 +17472,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17632,20 +17517,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18947,28 +18832,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Russian \n" @@ -22,7 +22,7 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && " "n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;\n" -"X-Generator: Weblate 5.2.1-rc\n" +"X-Generator: Weblate 5.3\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -57,7 +57,6 @@ msgid "Translate the guide" msgstr "Перевод руководств" #: ../source/contribute.rst:16 -#, fuzzy msgid "" "Most of the work on the |PyPUG| takes place on the `project's GitHub " "repository`__. To get started, check out the list of `open issues`__ and " @@ -82,11 +81,6 @@ msgid "Documentation types" msgstr "Типы документации" #: ../source/contribute.rst:34 -#, fuzzy -#| msgid "" -#| "This project consists of four distinct documentation types with specific " -#| "purposes. When proposing new additions to the project please pick the " -#| "appropriate documentation type." msgid "" "This project consists of four distinct documentation types with specific " "purposes. The project aspires to follow the `Diátaxis process`_ for creating " @@ -104,15 +98,15 @@ msgid "Tutorials" msgstr "Учебники" #: ../source/contribute.rst:44 -#, fuzzy msgid "" "Tutorials are focused on teaching the reader new concepts by accomplishing a " "goal. They are opinionated step-by-step guides. They do not include " "extraneous warnings or information. `example tutorial-style document`_." msgstr "" -"Тютории сосредоточены на преподавании читателю новых концепций путем " -"достижения цели. Они пошаговые гиды. Они не включают в себя внешние " -"предупреждения или информацию. `example teaching-style document`_." +"Учебники нацелены на обучение читателя новым понятиям путем достижения цели. " +"Они представляют собой пошаговые руководства, основанные на мнениях. Они не " +"содержат лишних предупреждений или информации. `Пример документа в стиле " +"учебника`_." #: ../source/contribute.rst:51 ../source/guides/index.rst:2 #: ../source/index.rst:69 @@ -120,7 +114,6 @@ msgid "Guides" msgstr "Руководства" #: ../source/contribute.rst:53 -#, fuzzy msgid "" "Guides are focused on accomplishing a specific task and can assume some " "level of pre-requisite knowledge. These are similar to tutorials, but have a " @@ -129,34 +122,32 @@ msgid "" "accomplishing the task. :doc:`example guide-style document `." msgstr "" -"Путеводители сосредоточены на выполнении конкретной задачи и могут взять на " -"себя некоторый уровень знаний, предназначенных. Они похожи на учебники, но " -"имеют узкую и четкую направленность и могут предоставить много оговорок и " -"дополнительную информацию по мере необходимости. Они также могут обсудить " -"несколько подходов к выполнению задачи. :doc:`example guide-style document " -"`." +"Руководства ориентированы на выполнение конкретной задачи и могут " +"предполагать наличие определенного уровня предварительных знаний. Они похожи " +"на учебники, но имеют узкую и четкую направленность и могут содержать много " +"предостережений и дополнительной информации, если это необходимо. В них " +"также может обсуждаться несколько подходов к выполнению задачи. :doc:`пример " +"документа в стиле руководства `." #: ../source/contribute.rst:60 ../source/discussions/index.rst:2 msgid "Discussions" msgstr "Обсуждения" #: ../source/contribute.rst:62 -#, fuzzy msgid "" "Discussions are focused on understanding and information. These explore a " "specific topic without a specific goal in mind. :doc:`example discussion-" "style document `." msgstr "" -"Дискуссии сосредоточены на понимании и информации. Они исследуют конкретную " -"тему без конкретной цели. :doc:`example discussion-style document " -"`." +"Дискуссии нацелены на понимание и получение информации. В них изучается " +"конкретная тема без определенной цели. :doc:`пример документа в стиле " +"дискуссии `." #: ../source/contribute.rst:67 msgid "Specifications" msgstr "Спецификации" #: ../source/contribute.rst:69 -#, fuzzy msgid "" "Specifications are reference documentation focused on comprehensively " "documenting an agreed-upon interface for interoperability between packaging " @@ -182,10 +173,6 @@ msgstr "" "переводе." #: ../source/contribute.rst:80 -#, fuzzy -#| msgid "" -#| "If you are experiencing issues while you are working on translations, " -#| "please open an issue on `Github`_." msgid "" "If you are experiencing issues while you are working on translations, please " "open an issue on `GitHub`_." @@ -210,16 +197,21 @@ msgid "" "guilabel:`Start new translation` at the bottom of the language list and add " "the language you want to translate." msgstr "" +"Если ваш язык не указан на «упаковке». python.org`_, нажмите кнопку :" +"guilabel: «Начните новый перевод» внизу языкового списка и добавьте язык, " +"который вы хотите перевести." #: ../source/contribute.rst:100 msgid "Following reStructuredText syntax" -msgstr "" +msgstr "После Текстовый синтаксис" #: ../source/contribute.rst:102 msgid "" "If you are not familiar with reStructuredText (RST) syntax, please read " "`this guide`_ before translating on Weblate." msgstr "" +"Если вы не знакомы с с синтаксисом reStructuredText (RST), пожалуйста, " +"прочитайте «это руководство» перед переводом на Weblate." #: ../source/contribute.rst:105 msgid "**Do not translate the text in reference directly**" @@ -253,10 +245,15 @@ msgid "" "locally in order to test your changes. In order to build this guide locally, " "you'll need:" msgstr "" +"Хотя это не требуется для внесения вклада, может быть полезно построить это " +"руководство на местном уровне, чтобы проверить ваши изменения. Чтобы " +"построить это руководство на местном уровне, вам нужно:" #: ../source/contribute.rst:130 msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" msgstr "" +":doc:`Nox `. Вы можете установить или обновить nox с помощью " +"``pip``:" #: ../source/contribute.rst:137 msgid "" @@ -265,15 +262,18 @@ msgid "" "guide:starting/installation>` to install Python 3.11 on your operating " "system." msgstr "" +"Python 3.11. Наши сценарии создания обычно тестируются только с Python 3.11. " +"См. :doc:`Hitchhiker's Guide to Pythoninstall instructions ` для установки Python 3.11 на вашей операционной " +"системе." #: ../source/contribute.rst:141 -#, fuzzy msgid "" "To build the guide, run the following shell command in the project's root " "folder:" msgstr "" -"Для сборки руководства выполните следующую команду bash в каталоге с " -"исходными файлами:" +"Для сборки руководства выполните следующую команду shell в корневом каталоге " +"проекта:" #: ../source/contribute.rst:147 msgid "" @@ -282,6 +282,10 @@ msgid "" "guide in web browser, but it's recommended to serve the guide using an HTTP " "server." msgstr "" +"После завершения процесса вы можете найти выход HTML в каталоге ``./build/" +"html``. Вы можете открыть файл ``index.html`` для просмотра руководства в " +"веб-браузере, но рекомендуется обслуживать руководство с помощью сервера " +"HTTP." #: ../source/contribute.rst:152 msgid "" @@ -306,10 +310,13 @@ msgid "" "readthedocs.org/projects/python-packaging-user-guide/. It's served from a " "custom domain and fronted by Fast.ly." msgstr "" +"Руководство развернуто через ReadTheDocs, и конфигурация живет на https://" +"readthedocs.org/projects/python-packaging-user-guide/. Он подается из " +"пользовательского домена и перед ним Fast.ly." #: ../source/contribute.rst:171 msgid "Style guide" -msgstr "" +msgstr "Стиль руководство" #: ../source/contribute.rst:173 msgid "" @@ -318,6 +325,10 @@ msgid "" "your contributions will help add to a cohesive whole and make it easier for " "your contributions to be accepted into the project." msgstr "" +"Это руководство по стилю имеет рекомендации о том, как вы должны писать |" +"PyPUG|. Прежде чем начать писать, пожалуйста, просмотрите его. Следуя " +"руководству по стилю, ваш вклад поможет добавить в единое целое и облегчит " +"принятие вашего вклада в проект." #: ../source/contribute.rst:180 msgid "Purpose" @@ -328,6 +339,8 @@ msgid "" "The purpose of the |PyPUG| is to be the authoritative resource on how to " "package, publish, and install Python projects using current tools." msgstr "" +"Цель |PyPUG| - быть авторитетным ресурсом о том, как упаковать, опубликовать " +"и установить Python проекты с использованием современных инструментов." #: ../source/contribute.rst:187 msgid "Scope" @@ -338,6 +351,8 @@ msgid "" "The guide is meant to answer questions and solve problems with accurate and " "focused recommendations." msgstr "" +"Руководство предназначено для ответа на вопросы и решения проблем с помощью " +"точных и целенаправленных рекомендаций." #: ../source/contribute.rst:192 msgid "" @@ -347,6 +362,11 @@ msgid "" "detail, while this guide describes only the parts of pip that are needed to " "complete the specific tasks described in this guide." msgstr "" +"Руководство не должно быть всеобъемлющим, и оно не предназначено для замены " +"документации отдельных проектов. Например, pip имеет десятки команд, опций и " +"настроек. Документация pip описывает каждую из них в деталях, в то время как " +"в этом руководстве описываются только те части pip, которые необходимы для " +"выполнения конкретных задач, описанных в настоящем руководстве." #: ../source/contribute.rst:200 msgid "Audience" @@ -354,7 +374,7 @@ msgstr "Аудитория" #: ../source/contribute.rst:202 msgid "The audience of this guide is anyone who uses Python with packages." -msgstr "" +msgstr "Аудитория этого руководства - любой, кто использует Python с пакетами." #: ../source/contribute.rst:204 msgid "" @@ -362,6 +382,9 @@ msgid "" "share your age, gender, education, culture, and more, but they deserve to " "learn about packaging just as much as you do." msgstr "" +"Не забывайте, что сообщество Python является большим и приветственным. " +"Читатели могут не делить свой возраст, пол, образование, культуру и многое " +"другое, но они заслуживают того, чтобы узнать о упаковке так же, как и вы." #: ../source/contribute.rst:208 msgid "" @@ -369,6 +392,10 @@ msgid "" "themselves as programmers. The audience of this guide includes astronomers " "or painters or students as well as professional software developers." msgstr "" +"В частности, имейте в виду, что не все люди, которые используют Python, " +"считают себя программистами. Аудитория этого руководства включает в себя " +"астрономов или художников или студентов, а также профессиональных " +"разработчиков программного обеспечения." #: ../source/contribute.rst:214 msgid "Voice and tone" @@ -379,6 +406,8 @@ msgid "" "When writing this guide, strive to write with a voice that's approachable " "and humble, even if you have all the answers." msgstr "" +"При написании этого руководства старайтесь писать голосом, который подходит " +"и скромен, даже если у вас есть все ответы." #: ../source/contribute.rst:219 msgid "" @@ -387,6 +416,10 @@ msgid "" "person has asked you a question and you know the answer. How do you respond? " "*That* is how you should write this guide." msgstr "" +"Представьте, что вы работаете над проектом Python с кем-то, кого вы знаете, " +"чтобы быть умным и квалифицированным. Вам нравится работать с ними, и им " +"нравится работать с вами. Этот человек задал вам вопрос, и вы знаете ответ. " +"Как ты реагируешь? * Вот как вы должны написать это руководство." #: ../source/contribute.rst:224 msgid "" @@ -397,6 +430,12 @@ msgid "" "hereby granted permission to end a sentence in a preposition, if that's what " "you want to end it with." msgstr "" +"Вот быстрая проверка: попробуйте читать вслух, чтобы понять голос и тон " +"вашего письма. Это звучит как что-то, что вы скажете или звучит так, будто " +"вы играете роль или произносите речь? Почувствуйте себя свободно в " +"использовании схваток и не волнуйтесь о том, чтобы придерживаться безумных " +"правил грамматики. Настоящим вам предоставляется разрешение на завершение " +"предложения в предположении, если это то, с чем вы хотите покончить." #: ../source/contribute.rst:231 msgid "" @@ -405,6 +444,10 @@ msgid "" "joke, but if you're covering a sensitive security recommendation, you might " "want to avoid jokes altogether." msgstr "" +"При написании руководства корректируйте свой тон на серьезность и сложность " +"темы. Если вы пишете вводный учебник, это нормально, чтобы шутить, но если " +"вы покрываете чувствительные рекомендации по безопасности, вы можете " +"избежать шуток в целом." #: ../source/contribute.rst:238 msgid "Conventions and mechanics" @@ -436,7 +479,7 @@ msgstr "Правильно: Чтобы установить его, запуст #: ../source/contribute.rst:252 msgid "**State assumptions**" -msgstr "" +msgstr "**Государственные предположения**" #: ../source/contribute.rst:249 msgid "" @@ -445,10 +488,14 @@ msgid "" "you're going to make assumptions, then say what assumptions that you're " "going to make." msgstr "" +"Избегайте делать негласные предположения. Чтение в Интернете означает, что " +"любая страница руководства может быть первой страницей руководства, которое " +"читатель когда-либо видел. Если вы собираетесь делать предположения, то " +"скажите, какие предположения вы собираетесь делать." #: ../source/contribute.rst:257 msgid "**Cross-reference generously**" -msgstr "" +msgstr "**Кросс-ссылки щедро**" #: ../source/contribute.rst:255 msgid "" @@ -456,6 +503,9 @@ msgid "" "that covers it, or link to a relevant document elsewhere. Save the reader a " "search." msgstr "" +"В первый раз, когда вы упоминаете инструмент или практику, обратитесь к той " +"части руководства, которая его охватывает, или обратитесь к соответствующему " +"документу в другом месте. Сохраните читателю поиск." #: ../source/contribute.rst:267 msgid "**Respect naming practices**" @@ -495,18 +545,21 @@ msgid "" "Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " "avoid pronouns entirely." msgstr "" +"Часто вы будете обращаться к читателю напрямую с *ты*, *ваш* и *ваш*. В " +"противном случае используйте гендерно-нейтральные местоимения *они *, * их * " +"и * их * или полностью избегайте местоимений." #: ../source/contribute.rst:0 msgid "Wrong: A maintainer uploads the file. Then he…" -msgstr "" +msgstr "Неправильно: Сопровождающий загружает файл. Затем он…" #: ../source/contribute.rst:0 msgid "Right: A maintainer uploads the file. Then they…" -msgstr "" +msgstr "Правильно: Сопровождающий загружает файл. Затем они…" #: ../source/contribute.rst:0 msgid "Right: A maintainer uploads the file. Then the maintainer…" -msgstr "" +msgstr "Правильно: Сопровождающий загружает файл. Затем сопровождающий…" #: ../source/contribute.rst:288 msgid "**Headings**" @@ -519,12 +572,19 @@ msgid "" "reader might want to know *How do I install MyLibrary?* so a good heading " "might be *Install MyLibrary*." msgstr "" +"Пишите заголовки, в которых используются слова, которые читатель ищет. " +"Хорошим способом сделать это является то, чтобы ваш заголовок завершал " +"подразумеваемый вопрос. Например, читатель может захотеть узнать *Как " +"установить MyLibrary?*, поэтому хорошим заголовком будет *Установить " +"MyLibrary*." #: ../source/contribute.rst:284 msgid "" "In section headings, use sentence case. In other words, write headings as " "you would write a typical sentence." msgstr "" +"В заголовках разделов используйте падеж предложения. Другими словами, пишите " +"заголовки так, как вы бы написали обычное предложение." #: ../source/contribute.rst:0 msgid "Wrong: Things You Should Know About Python" @@ -543,12 +603,15 @@ msgid "" "In body text, write numbers one through nine as words. For other numbers or " "numbers in tables, use numerals." msgstr "" +"В основном тексте пишите числа от 1 до 9 как слова. Для остальных чисел или " +"чисел в таблицах используйте цифры." #: ../source/discussions/deploying-python-applications.rst:4 msgid "Deploying Python applications" msgstr "Развёртывание приложений на Python'е" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -567,6 +630,7 @@ msgid "Incomplete" msgstr "Незавершено" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -577,7 +641,7 @@ msgstr "Последняя проверка" #: ../source/discussions/deploying-python-applications.rst:7 msgid "2021-8-24" -msgstr "" +msgstr "2021-8-24" #: ../source/discussions/deploying-python-applications.rst:11 #: ../source/specifications/externally-managed-environments.rst:130 @@ -591,7 +655,7 @@ msgstr "Поддержка нескольких аппаратных платф #: ../source/discussions/deploying-python-applications.rst:37 msgid "OS packaging & installers" -msgstr "" +msgstr "Упаковка и инсталляторы ОС" #: ../source/discussions/deploying-python-applications.rst:49 #: ../source/discussions/deploying-python-applications.rst:86 @@ -611,6 +675,13 @@ msgid "" "tool downloads the specified Python-interpreter for Windows and packages it " "with all the dependencies in a single Windows-executable installer." msgstr "" +"`Pynsist `__ - это инструмент, который " +"упаковывает программы на Python вместе с Python-интерпретатором в единый " +"инсталлятор, основанный на NSIS. В большинстве случаев упаковка требует от " +"пользователя только выбора версии Python-интерпретатора и объявления " +"зависимостей программы. Утилита загружает указанный Python-интерпретатор для " +"Windows и упаковывает его вместе со всеми зависимостями в единый Windows-" +"исполняемый инсталлятор." #: ../source/discussions/deploying-python-applications.rst:67 msgid "" @@ -619,6 +690,10 @@ msgid "" "application directory, independent of any other Python installation on the " "computer." msgstr "" +"Установленная программа может быть запущена из короткого пути, который " +"установщик добавляет к start-menu. Он использует интерпретатор Python, " +"установленный в его каталоге приложений, независимо от любой другой " +"установки Python на компьютере." #: ../source/discussions/deploying-python-applications.rst:71 msgid "" @@ -627,6 +702,10 @@ msgid "" "GUI) in the :any:`documentation `. The tool is released under " "the MIT-licence." msgstr "" +"Большим преимуществом Pynsist является то, что пакеты Windows могут быть " +"построены на Linux. Существует несколько примеров для различных видов " +"программ (консоль, GUI) в :any:`documentation `. Инструмент " +"выпущен под лицензией MIT." #: ../source/discussions/deploying-python-applications.rst:77 msgid "Application bundles" @@ -647,6 +726,14 @@ msgid "" "supported. The distutils extension is released under the MIT-licence and " "Mozilla Public License 2.0." msgstr "" +"`__ Это расширение отключения, которое " +"позволяет создавать автономные Windows исполняемые программы (32-битные и 64-" +"битные) от Python. Python версии, включенные в официальный цикл разработки, " +"поддерживаются (относится к `Status of Python branches`__). py2exe может " +"создавать исполняемые консоли и исполняемые окна (GUI). Сервисы по " +"строительству окон и серверы DLL/EXE COM могут работать, но они не " +"поддерживаются активно. Расширение Distutils выпущено под лицензией MIT и " +"публичной лицензией Mozilla 2.0." #: ../source/discussions/deploying-python-applications.rst:103 msgid "macOS" @@ -664,13 +751,18 @@ msgid "" "applications, it cannot create Mac applications on other platforms. py2app " "is released under the MIT-license." msgstr "" +"`py2app `__ - это команда Python " +"setuptools, которая позволит вам создавать автономные пакеты приложений и " +"плагинов для macOS из скриптов Python. Обратите внимание, что py2app ДОЛЖЕН " +"использоваться на macOS для создания приложений, он не может создавать Mac-" +"приложения на других платформах. py2app выпускается под MIT-лицензией." #: ../source/discussions/deploying-python-applications.rst:115 msgid "Unix (including Linux and macOS)" -msgstr "" +msgstr "Unix (включая Linux и macOS)" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "pex" @@ -684,17 +776,164 @@ msgid "" "meaning that a single pex file can be portable across Linux and macOS. pex " "is released under the Apache License 2.0." msgstr "" +"pex `__ - это библиотека для создания " +"файлов .pex (Python EXecutable), которые являются исполняемыми окружениями " +"Python в духе virtualenvs. pex является расширением идей, изложенных в :pep:" +"`441`, и делает развертывание приложений Python таким же простым, как cp. " +"Файлы pex могут даже включать несколько дистрибутивов Python, специфичных " +"для конкретной платформы, что означает, что один файл pex может быть " +"переносимым в Linux и macOS. pex выпущен в соответствии с Apache License 2.0." #: ../source/discussions/deploying-python-applications.rst:129 msgid "Configuration management" msgstr "Управление конфигурацией" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution package vs. import package" +msgstr "Пакет дистрибутива" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "Что такое дистрибутивный пакет?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "Что такое пакет импорта?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " "specific topic. If you're just trying to get stuff done, see :doc:`/guides/" "index`." msgstr "" +"**Дискуссии** направлены на предоставление исчерпывающей информации по " +"определенной теме. Если вы просто хотите сделать что-то, смотрите :doc:`/" +"guides/index`." #: ../source/discussions/install-requires-vs-requirements.rst:5 msgid "install_requires vs requirements files" @@ -711,23 +950,33 @@ msgid "" "correctly. When the project is installed by :ref:`pip`, this is the " "specification that is used to install its dependencies." msgstr "" +"``install_requires`` - это ключевое слово :ref:`setuptools` :file:`setup." +"py`, которое должно использоваться для указания того, что проекту " +"**минимально** необходимо для корректной работы. Когда проект " +"устанавливается с помощью :ref:`pip`, это спецификация, которая используется " +"для установки его зависимостей." #: ../source/discussions/install-requires-vs-requirements.rst:16 msgid "" "For example, if the project requires A and B, your ``install_requires`` " "would be like so:" msgstr "" +"Например, если проект требует A и B, ваш ``install_requires`` будет " +"выглядеть так:" #: ../source/discussions/install-requires-vs-requirements.rst:26 msgid "" "Additionally, it's best practice to indicate any known lower or upper bounds." msgstr "" +"Кроме того, лучше всего указать все известные нижние и верхние границы." #: ../source/discussions/install-requires-vs-requirements.rst:28 msgid "" "For example, it may be known, that your project requires at least v1 of 'A', " "and v2 of 'B', so it would be like so:" msgstr "" +"Например, может быть известно, что ваш проект требует по крайней мере v1 'A' " +"и v2 'B', так что это было бы так:" #: ../source/discussions/install-requires-vs-requirements.rst:38 msgid "" @@ -735,6 +984,9 @@ msgid "" "breaks the compatibility of your project with v2 of 'A' and later, so it " "makes sense to not allow v2:" msgstr "" +"Также может быть известно, что проект «A» ввел изменение в его v2, которое " +"нарушает совместимость вашего проекта с v2 «A», а затем, поэтому имеет смысл " +"не разрешать v2:" #: ../source/discussions/install-requires-vs-requirements.rst:49 msgid "" @@ -743,6 +995,11 @@ msgid "" "dependencies of your dependencies). This is overly-restrictive, and " "prevents the user from gaining the benefit of dependency upgrades." msgstr "" +"Не считается лучшей практикой использовать ``install_requires`` для " +"определения зависимостей к конкретным версиям или для указания " +"подзависимости (т.е. зависимости от ваших зависимостей). Это чрезмерно " +"ограничено и не позволяет пользователю получать выгоду от обновления " +"зависимости." #: ../source/discussions/install-requires-vs-requirements.rst:54 msgid "" @@ -753,6 +1010,11 @@ msgid "" "\"Concrete\") is to be determined at install time using :ref:`pip` options. " "[1]_" msgstr "" +"Наконец, важно понимать, что ``install_requires`` - это список " +"\"Абстрактных\" требований, т.е. просто имена и ограничения версий, которые " +"не определяют, откуда будут выполняться зависимости (т.е. из какого индекса " +"или источника). Где (т.е. как они должны быть сделаны \"конкретными\"), " +"определяется во время установки с помощью опций :ref:`pip`. [1]_" #: ../source/discussions/install-requires-vs-requirements.rst:62 #: ../source/tutorials/installing-packages.rst:464 @@ -764,6 +1026,8 @@ msgid "" ":ref:`Requirements Files ` described most simply, " "are just a list of :ref:`pip:pip install` arguments placed into a file." msgstr "" +":ref:`Requirements Files `, описанный проще всего, - " +"это всего лишь список :ref:`pip:pip install` аргументов, помещенных в файл." #: ../source/discussions/install-requires-vs-requirements.rst:67 msgid "" @@ -771,6 +1035,9 @@ msgid "" "ref:`Requirements Files ` are often used to define " "the requirements for a complete Python environment." msgstr "" +"В то время как ``install_requires`` определяет зависимости для одного " +"проекта, :ref:`Requirements Files ` часто " +"используются для определения требований для полной Python среды." #: ../source/discussions/install-requires-vs-requirements.rst:71 msgid "" @@ -779,6 +1046,9 @@ msgid "" "achieving :ref:`repeatable installations ` of a complete " "environment." msgstr "" +"В то время как требования ``install_requires`` являются минимальными, файлы " +"требований часто содержат исчерпывающий список пинированных версий для " +"достижения :ref:`repeatable installations ` полной среды." #: ../source/discussions/install-requires-vs-requirements.rst:76 msgid "" @@ -788,6 +1058,11 @@ msgid "" "\"Concrete\", i.e. associated with a particular index or directory of " "packages. [1]_" msgstr "" +"В то время как ``install_requires`` требования являются \"Abstract\", т.е. " +"не связаны с каким-либо конкретным индексом, файлы требований часто содержат " +"pip опции, такие как ``--index-url`` или ``--find-links``, чтобы сделать " +"требования \"Concrete\", т.е. связанные с конкретным индексом или каталогом " +"пакетов. [1]_" #: ../source/discussions/install-requires-vs-requirements.rst:82 msgid "" @@ -795,12 +1070,18 @@ msgid "" "during an install, requirements files are not, and only are used when a user " "specifically installs them using ``python -m pip install -r``." msgstr "" +"В то время как метаданные ``install_requires`` автоматически анализируются " +"pip во время установки, файлы требований не являются и используются только " +"тогда, когда пользователь специально устанавливает их с помощью ``python -m " +"pip install -r``." #: ../source/discussions/install-requires-vs-requirements.rst:88 msgid "" "For more on \"Abstract\" vs \"Concrete\" requirements, see https://caremad." "io/posts/2013/07/setup-vs-requirement/." msgstr "" +"Подробнее о требованиях \"Абстрактные\" и \"Конкретные\" см. на сайте " +"https://caremad.io/posts/2013/07/setup-vs-requirement/." #: ../source/discussions/pip-vs-easy-install.rst:6 msgid "pip vs easy_install" @@ -814,6 +1095,11 @@ msgid "" "Index (PyPI)>` using requirement specifiers, and automatically installing " "dependencies." msgstr "" +":ref:`easy_install `, теперь `deprecated`_, был выпущен в 2004 " +"как часть :ref:`setuptools`. Он был примечателен в то время для установки :" +"term:`packages ` из :term:`PyPI `Python Индекса пакетов (PyPI)>` с использованием спецификаторов " +"требований и автоматической установки зависимостей." #: ../source/discussions/pip-vs-easy-install.rst:14 msgid "" @@ -825,12 +1111,20 @@ msgid "" "introducing the idea of :ref:`Requirements Files `, " "which gave users the power to easily replicate environments." msgstr "" +":ref:`pip` появился позже в 2008, в качестве альтернативы :ref:`easy_install " +"`, хотя все еще в значительной степени построен на :ref:" +"`setuptools` компонентах. Это было примечательно в то время для *не* " +"установки пакетов как :term:`Eggs ` или от :term:`Eggs ` (но, " +"скорее, просто как «плоские» пакеты от :term:`sdists `), и введение идеи :ref:`Requirements Files `, которая давала пользователям возможность легко " +"реплицировать среды." #: ../source/discussions/pip-vs-easy-install.rst:22 msgid "" "Here's a breakdown of the important differences between pip and the " "deprecated easy_install:" -msgstr "" +msgstr "Вот разбивка важных различий между pip и обесцененным easy_install:" #: ../source/discussions/pip-vs-easy-install.rst:25 msgid "**pip**" @@ -864,7 +1158,7 @@ msgstr "Да" #: ../source/discussions/pip-vs-easy-install.rst:54 #: ../source/discussions/pip-vs-easy-install.rst:57 msgid "No" -msgstr "" +msgstr "Нет" #: ../source/discussions/pip-vs-easy-install.rst:30 msgid "Uninstall Packages" @@ -872,7 +1166,7 @@ msgstr "Удаление пакетов" #: ../source/discussions/pip-vs-easy-install.rst:30 msgid "Yes (``python -m pip uninstall``)" -msgstr "" +msgstr "Да (``python -m pip uninstall``)" #: ../source/discussions/pip-vs-easy-install.rst:32 msgid "Dependency Overrides" @@ -888,7 +1182,7 @@ msgstr "Перечисление установленных пакетов" #: ../source/discussions/pip-vs-easy-install.rst:35 msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" -msgstr "" +msgstr "Да (``python -m pip list`` и ``python -m pip freeze``)" #: ../source/discussions/pip-vs-easy-install.rst:38 msgid ":pep:`438` Support" @@ -900,7 +1194,7 @@ msgstr "Формат установки" #: ../source/discussions/pip-vs-easy-install.rst:41 msgid "'Flat' packages with :file:`egg-info` metadata." -msgstr "" +msgstr "'Плоские' пакеты с метаданными :file:`egg-info`." #: ../source/discussions/pip-vs-easy-install.rst:41 msgid "Encapsulated Egg format" @@ -912,7 +1206,7 @@ msgstr "Изменение ``sys.path``" #: ../source/discussions/pip-vs-easy-install.rst:48 msgid "Installs from :term:`Eggs `" -msgstr "Установка из :term:`яиц `" +msgstr "Установка из :term:`Eggs `" #: ../source/discussions/pip-vs-easy-install.rst:51 msgid "`pylauncher support`_" @@ -953,11 +1247,11 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:6 msgid "Is ``setup.py`` deprecated?" -msgstr "" +msgstr "Является ли ``setup.py`` обесцененным?" #: ../source/discussions/setup-py-deprecated.rst:8 msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." -msgstr "" +msgstr "Нет, :термин:`setup.py` и :ref:`setuptools' не амортизируются." #: ../source/discussions/setup-py-deprecated.rst:10 msgid "" @@ -965,78 +1259,81 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" +"Setuptools вполне можно использовать в качестве :term:`build backend` для " +"упаковки Python-проектов. А :file:`setup.py` - это правильный " +"конфигурационный файл для :ref:`setuptools`, который, к примеру, написан на " +"Python, а не на *TOML* (подобная практика используется и в других " +"инструментах, таких как *nox* и его конфигурационный файл :file:`noxfile." +"py`, или *pytest* и :file:`conftest.py`)." #: ../source/discussions/setup-py-deprecated.rst:18 msgid "" "However, ``python setup.py`` and the use of :file:`setup.py` as a command " "line tool are deprecated." msgstr "" +"Однако ``python setup.py`` и использование :file:`setup.py' в качестве " +"инструмента командной строки обесцениваются." #: ../source/discussions/setup-py-deprecated.rst:21 msgid "" "This means that commands such as the following **MUST NOT** be run anymore:" msgstr "" +"Это означает, что команды, такие как следующий **MUST NO**, будут " +"выполняться больше:" #: ../source/discussions/setup-py-deprecated.rst:23 #: ../source/discussions/setup-py-deprecated.rst:35 #: ../source/guides/modernize-setup-py-project.rst:32 -#, fuzzy msgid "``python setup.py install``" -msgstr "python_requires" +msgstr "``python setup.py install``" #: ../source/discussions/setup-py-deprecated.rst:24 #: ../source/discussions/setup-py-deprecated.rst:37 #: ../source/guides/modernize-setup-py-project.rst:34 msgid "``python setup.py develop``" -msgstr "" +msgstr "``python setup.py develop``" #: ../source/discussions/setup-py-deprecated.rst:25 #: ../source/discussions/setup-py-deprecated.rst:39 #: ../source/guides/modernize-setup-py-project.rst:36 -#, fuzzy msgid "``python setup.py sdist``" -msgstr "python_requires" +msgstr "``python setup.py sdist``" #: ../source/discussions/setup-py-deprecated.rst:26 #: ../source/discussions/setup-py-deprecated.rst:41 #: ../source/guides/modernize-setup-py-project.rst:38 msgid "``python setup.py bdist_wheel``" -msgstr "" +msgstr "``python setup.py bdist_wheel``" #: ../source/discussions/setup-py-deprecated.rst:30 msgid "What commands should be used instead?" -msgstr "" +msgstr "Какие команды следует использовать вместо этого?" #: ../source/discussions/setup-py-deprecated.rst:33 #: ../source/guides/modernize-setup-py-project.rst:30 -#, fuzzy -#| msgid "Rarely Used Fields" msgid "Deprecated" -msgstr "Редко используемые поля" +msgstr "Устаревшее" #: ../source/discussions/setup-py-deprecated.rst:33 #: ../source/guides/modernize-setup-py-project.rst:30 -#, fuzzy -#| msgid "Tool recommendations" msgid "Recommendation" -msgstr "Рекомендации по инструментам" +msgstr "Рекомендации" #: ../source/discussions/setup-py-deprecated.rst:35 #: ../source/guides/modernize-setup-py-project.rst:32 -#, fuzzy msgid "``python -m pip install .``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``python -m pip install .``" #: ../source/discussions/setup-py-deprecated.rst:37 #: ../source/guides/modernize-setup-py-project.rst:34 msgid "``python -m pip install --editable .``" -msgstr "" +msgstr "``python -m pip install --editable .``" #: ../source/discussions/setup-py-deprecated.rst:39 msgid "``python -m build`` [#needs-build]_" -msgstr "" +msgstr "``python -m build`` [#needs-build]_" #: ../source/discussions/setup-py-deprecated.rst:45 msgid "" @@ -1045,6 +1342,10 @@ msgid "" "what ``python -m build`` does. If necessary the ``--sdist`` and ``--wheel`` " "options can be used to generate only one or the other." msgstr "" +"Это требует :ref:`build' зависимости. Рекомендуется всегда строить и " +"публиковать как распределение источника, так и колесо проекта, что и делает " +"``python -m build``. При необходимости опции ``-sdist`` и ``--wheel`` могут " +"быть использованы для создания только одного или другого." #: ../source/discussions/setup-py-deprecated.rst:52 msgid "" @@ -1057,6 +1358,15 @@ msgid "" "on the local filesystem as argument to its ``install`` sub-command. So this " "would also be a valid command: ``python -m pip install path/to/project``." msgstr "" +"Для установки проекта, основанного на setuptools, обычно выполнялась команда " +"``install`` от :file:``setup.py``, например: ``python setup.py install``. В " +"настоящее время рекомендуется использовать :ref:`pip` напрямую с командой, " +"подобной этой: ``python -m pip install .``. Где точка ``.`` на самом деле " +"является путем к файловой системе, это обозначение пути к текущему каталогу. " +"Действительно, *pip* принимает путь к каталогу дерева исходников проекта в " +"локальной файловой системе в качестве аргумента своей подкоманды " +"``install``. Таким образом, это также будет правильной командой: ``python -m " +"pip install path/to/project``." #: ../source/discussions/setup-py-deprecated.rst:65 msgid "" @@ -1064,6 +1374,9 @@ msgid "" "``python setup.py develop`` one can use the ``--editable`` option of pip's " "*install* sub-command: ``python -m pip install --editable .``." msgstr "" +"Что касается установки в режиме *develop* aka *editable*, то вместо ``python " +"setup.py develop`` можно использовать опцию ``--editable`` в подкоманде pip " +"*install*: ``python -m pip install --editable .``." #: ../source/discussions/setup-py-deprecated.rst:70 msgid "" @@ -1075,277 +1388,307 @@ msgid "" "generate only one or the other. Note that the build tool needs to be " "installed separately." msgstr "" +"Один из рекомендуемых, простых и понятных методов сборки :term:`source " +"дистрибутивов ` и :term:`wheels " +"` заключается в использовании инструмента :ref:`build` с командой " +"типа ``python -m build``, которая запускает генерацию обоих форматов " +"дистрибутивов. При необходимости опции ``--sdist`` и ``--wheel`` могут быть " +"использованы для генерации только одного или другого. Обратите внимание, что " +"инструмент сборки должен быть установлен отдельно." #: ../source/discussions/setup-py-deprecated.rst:80 msgid "" "The command ``python setup.py install`` was deprecated in setuptools version " "*58.3.0*." msgstr "" +"Команда ``python setup.pyinstall`` была обесценена в setuptools версии " +"*58.3.0*." #: ../source/discussions/setup-py-deprecated.rst:85 msgid "What about other commands?" -msgstr "" +msgstr "Как насчет других команд?" #: ../source/discussions/setup-py-deprecated.rst:87 msgid "What are some replacements for the other ``python setup.py`` commands?" -msgstr "" +msgstr "Каковы некоторые замены для других команд ``python setup.py``?" #: ../source/discussions/setup-py-deprecated.rst:91 -#, fuzzy msgid "``python setup.py test``" -msgstr "python_requires" +msgstr "``python setup.py test``" #: ../source/discussions/setup-py-deprecated.rst:93 msgid "The recommendation is to use a test runner such as pytest_." msgstr "" +"Рекомендация заключается в использовании тестового бегуна, такого как " +"pytest_." #: ../source/discussions/setup-py-deprecated.rst:99 msgid "" "``python setup.py check``, ``python setup.py register``, and ``python setup." "py upload``" msgstr "" +"``python setup.py check``, ``python setup.py register`` и ``python setup.py " +"upload``" #: ../source/discussions/setup-py-deprecated.rst:101 msgid "A trusted replacement is :ref:`twine`:" -msgstr "" +msgstr "Доверенная замена:ref:`twine':" #: ../source/discussions/setup-py-deprecated.rst:103 -#, fuzzy -msgid "``python -m twine check``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" #: ../source/discussions/setup-py-deprecated.rst:104 -#, fuzzy -msgid "``python -m twine register``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "``python -m twine register dist/*.whl`` [#not-pypi]_" #: ../source/discussions/setup-py-deprecated.rst:105 -#, fuzzy -msgid "``python -m twine upload``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" -#: ../source/discussions/setup-py-deprecated.rst:109 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"Не требуется и не поддерживается на:term:`PyPI `. Но может потребоваться и в других :термин:`package index>` " +"(например:ref:`devpi`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" -msgstr "python_requires" +msgstr "``python setup.py --version``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" +"Возможное заменяющее решение (среди прочих) - полагаться на setuptools-scm_:" -#: ../source/discussions/setup-py-deprecated.rst:113 -#, fuzzy -msgid "``python -m setuptools-scm``" -msgstr "Используйте ``pip`` для установки Pipenv:" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools-scm``" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" -msgstr "" +msgstr "Оставшиеся команды" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" +"В настоящем руководстве не предлагаются решения для замены этих команд:" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" -msgstr "" +msgstr "``alias``" -#: ../source/discussions/setup-py-deprecated.rst:127 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" -msgstr "``text/x-rst``" +msgstr "``bdist``" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" -msgstr "" +msgstr "``bdist_dumb``" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" -msgstr "" +msgstr "``bdist_egg``" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" -msgstr "" +msgstr "``bdist_rpm``" -#: ../source/discussions/setup-py-deprecated.rst:131 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``build``" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" -msgstr "" +msgstr "``build_clib``" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" -msgstr "" +msgstr "``build_ext``" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" -msgstr "" +msgstr "``build_py``" -#: ../source/discussions/setup-py-deprecated.rst:135 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" -msgstr "scripts" +msgstr "``build_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" -msgstr "" +msgstr "``clean``" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" -msgstr "" +msgstr "``dist_info``" -#: ../source/discussions/setup-py-deprecated.rst:138 -#, fuzzy -#| msgid "**easy_install**" +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "**easy_install**" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" -msgstr "" +msgstr "``editable_wheel``" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" -msgstr "" +msgstr "``egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:141 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``install``" -#: ../source/discussions/setup-py-deprecated.rst:142 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``install_data``" -#: ../source/discussions/setup-py-deprecated.rst:143 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" -msgstr "install_requires" +msgstr "``install_egg_info``" -#: ../source/discussions/setup-py-deprecated.rst:144 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" -msgstr "install_requires" +msgstr "``install_headers``" -#: ../source/discussions/setup-py-deprecated.rst:145 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" -msgstr "install_requires" +msgstr "``install_lib``" -#: ../source/discussions/setup-py-deprecated.rst:146 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" -msgstr "console_scripts" +msgstr "``install_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" -msgstr "" +msgstr "``rotate``" -#: ../source/discussions/setup-py-deprecated.rst:148 -#, fuzzy +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" -msgstr "scripts" +msgstr "``saveopts``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" -msgstr "" +msgstr "``setopt``" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" -msgstr "" +msgstr "``upload_docs``" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" -msgstr "" +msgstr "Что насчет пользовательских команд?" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " "any other similar tool. Some examples of such tools are: chuy, make, nox or " "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" +"Аналогично, пользовательские :file:`setup.py' команды депрецируются. " +"Рекомендация состоит в том, чтобы перенести эти пользовательские команды на " +"инструмент для выполнения задач или любой другой аналогичный инструмент. " +"Некоторые примеры таких инструментов: chuy, make, nox или tox, pydoit, " +"pyinvoke, taskipy и thx." -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" -msgstr "" +msgstr "Как насчет пользовательских шагов?" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" +"Настроить шаги, которые, например, либо переписать существующие шаги, такие " +"как ``build_py``, ``build_ext`` и ``bdist_wheel`` или добавить новые шаги " +"сборки, не обесцениваются. Они будут автоматически называться, как и " +"ожидалось." -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" -msgstr "" +msgstr "Следует ли исключить ``setup.py``?" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" +"Хотя использование :file:`setup.py' в качестве исполняемого скрипта " +"депрецируется, его использование в качестве файла конфигурации для " +"setuptools абсолютно нормально. :file:`setup.py`, вероятно, не требуется " +"никаких изменений." -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" -msgstr "" +msgstr "Является ли ``pyproject.toml`` обязательным?" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" +"Хотя это еще не технически необходимо, это **STRONGLY RECOMMENDED** для " +"проекта иметь :file:`pyproject. toml' файл в корне своего исходного дерева с " +"таким контентом:" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" +"Руководство:ref: \" Modernize-setup-py-project \" имеет больше деталей об " +"этом." -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " "table is to assume that the :term:`build backend ` is " "setuptools." msgstr "" +"Стандартное обратное поведение для :term:`build frontend ` в " +"отсутствие :file:`pyproject.toml' файла и его ``[build-system]`` таблица " +"предполагает, что :term:`build backend ` является setuptools." -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" -msgstr "" +msgstr "Почему? Что все это значит?" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" +"Один из способов взглянуть на это заключается в том, что сфера setuptools " +"теперь была сведена к роли опоры." -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" -msgstr "" +msgstr "Где почитать об этом?" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" -msgstr "" +msgstr "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" -msgstr "" +msgstr ":doc:`setuptools:deprecated/commands`" #: ../source/discussions/src-layout-vs-flat-layout.rst:5 msgid "src layout vs flat layout" -msgstr "" +msgstr "src-макет против плоского макета" #: ../source/discussions/src-layout-vs-flat-layout.rst:7 msgid "" @@ -1353,6 +1696,9 @@ msgid "" "repository, such that the various configuration files and :term:`import " "packages ` are all in the top-level directory." msgstr "" +"«плоский макет» относится к организации файлов проекта в папке или " +"репозитории, так что различные файлы конфигурации и :термин: «импортные " +"пакеты ` все в директории верхнего уровня." #: ../source/discussions/src-layout-vs-flat-layout.rst:25 msgid "" @@ -1361,18 +1707,26 @@ msgid "" "term:`import packages `) into a subdirectory. This " "subdirectory is typically named ``src/``, hence \"src layout\"." msgstr "" +"src раскладка\" отличается от плоской раскладки тем, что код, который должен " +"быть импортируемым (например, ``import awesome_package``, также известный " +"как :term:`import packages `), перемещается в подкаталог. " +"Этот подкаталог обычно называется ``rc/``, отсюда и \"src раскладка\"." #: ../source/discussions/src-layout-vs-flat-layout.rst:45 msgid "" "Here's a breakdown of the important behaviour differences between the src " "layout and the flat layout:" msgstr "" +"Вот разбивка важных различий в поведении между макетом дуги и плоской " +"компоновкой:" #: ../source/discussions/src-layout-vs-flat-layout.rst:48 msgid "" "The src layout requires installation of the project to be able to run its " "code, and the flat layout does not." msgstr "" +"Схема арки требует установки проекта, чтобы иметь возможность запустить его " +"код, а плоской планировки нет." #: ../source/discussions/src-layout-vs-flat-layout.rst:51 msgid "" @@ -1381,12 +1735,18 @@ msgid "" "` is used for development and a " "regular installation is used for testing)." msgstr "" +"Это означает, что планировка дуги включает в себя дополнительный шаг в " +"процессе разработки проекта (как правило, :doc: «отредактируемая установка " +"` используется для разработки и для " +"тестирования используется регулярная установка)." #: ../source/discussions/src-layout-vs-flat-layout.rst:56 msgid "" "The src layout helps prevent accidental usage of the in-development copy of " "the code." msgstr "" +"Схема кружево помогает предотвратить случайное использование копии кода в " +"разработке." #: ../source/discussions/src-layout-vs-flat-layout.rst:59 msgid "" @@ -1398,6 +1758,13 @@ msgid "" "packaging tooling, which could result in files not being included in a " "distribution." msgstr "" +"Это актуально, поскольку интерпретатор Python включает текущий рабочий " +"каталог в качестве первого пункта на пути импорта. Это означает, что если " +"пакет импорта существует в текущем рабочем каталоге с тем же названием, что " +"и установленный пакет импорта, будет использоваться вариант из текущего " +"рабочего каталога. Это может привести к тонкой неправильной настройке " +"инструментов упаковки проекта, что может привести к тому, что файлы не будут " +"включены в распределение." #: ../source/discussions/src-layout-vs-flat-layout.rst:66 msgid "" @@ -1405,6 +1772,9 @@ msgid "" "separate from the root directory of the project, ensuring that the installed " "copy is used." msgstr "" +"Схема src помогает избежать этого, сохраняя импортные пакеты в каталоге " +"отдельно от корневого каталога проекта, обеспечивая использование " +"установленной копии." #: ../source/discussions/src-layout-vs-flat-layout.rst:70 msgid "" @@ -1412,6 +1782,9 @@ msgid "" "userguide/development_mode>` is only able to import files that were meant to " "be importable." msgstr "" +"Схема src помогает обеспечить, чтобы :doc:`editableinstall ` смог импортировать только файлы, которые должны " +"были быть импортированы." #: ../source/discussions/src-layout-vs-flat-layout.rst:74 msgid "" @@ -1419,6 +1792,9 @@ msgid "" "using a `path configuration file `_ that adds the directory to the import path." msgstr "" +"Это особенно актуально, когда редактируемая установка реализована с помощью " +"файла `_ это добавляет каталог " +"к пути импорта." #: ../source/discussions/src-layout-vs-flat-layout.rst:78 msgid "" @@ -1427,6 +1803,11 @@ msgid "" "``noxfile.py``) on the import path. This would make certain imports work in " "editable installations but not regular installations." msgstr "" +"В плоском макете будут добавлены другие файлы проекта (например: ``README." +"md``, ``tox.ini``) и файлы конфигурации упаковки/инструмента (например: " +"``setup.py``, ``noxfile.py``) на пути импорта. Это позволило бы производить " +"определенные импортные работы на редактируемых установках, но не на обычных " +"установках." #: ../source/discussions/wheel-vs-egg.rst:5 msgid "Wheel vs Egg" @@ -1438,30 +1819,42 @@ msgid "" "the use case of needing an install artifact that doesn't require building or " "compilation, which can be costly in testing and production workflows." msgstr "" +":термин: `Wheel' и :term:`Egg' - это оба формата упаковки, которые " +"направлены на поддержку случая использования объекта установки, который не " +"требует строительства или компиляции, что может быть дорогостоящим в " +"тестировании и производстве рабочих процессов." #: ../source/discussions/wheel-vs-egg.rst:11 msgid "" "The :term:`Egg` format was introduced by :ref:`setuptools` in 2004, whereas " "the :term:`Wheel` format was introduced by :pep:`427` in 2012." msgstr "" +":term:`Egg` format was introduced by :ref:`setuptools' in 2004, whereas the :" +"term:` В 2012 году в формате < < Колесо > > был представлен документ :pep:" +"`427 > > ." #: ../source/discussions/wheel-vs-egg.rst:14 msgid "" ":term:`Wheel` is currently considered the standard for :term:`built ` and :term:`binary ` packaging for Python." msgstr "" +":term:`Wheel` в настоящее время считается стандартом для :term:`built ` и :term:`binary ` упаковки для Python." #: ../source/discussions/wheel-vs-egg.rst:17 msgid "" "Here's a breakdown of the important differences between :term:`Wheel` and :" "term:`Egg`." msgstr "" +"Вот разбивка важных различий между :термин: \"Wheel\" и :term: \"Egg\"." #: ../source/discussions/wheel-vs-egg.rst:20 msgid "" ":term:`Wheel` has an :doc:`official standard specification `. :term:`Egg` did not." msgstr "" +"У :term:`Wheel` есть :doc:`официальная спецификация стандарта `. У :term:`Egg` ее нет." #: ../source/discussions/wheel-vs-egg.rst:24 msgid "" @@ -1470,6 +1863,10 @@ msgid "" "runtime installation format (if left zipped), and was designed to be " "importable." msgstr "" +":term:`Wheel` - это формат :term:`distribution `, т.е. " +"формат упаковки. [1]_ :term:`Egg` - это одновременно и формат дистрибутива, " +"и формат установки во время выполнения (если оставить его запечатанным), и " +"он был разработан для импорта." #: ../source/discussions/wheel-vs-egg.rst:28 msgid "" @@ -1479,12 +1876,18 @@ msgid "" "\"universal\", similar to an :term:`sdist `." msgstr "" +"Архивы :term:`Wheel` не включают файлы .pyc. Поэтому, если дистрибутив " +"содержит только файлы Python (т.е. не содержит скомпилированных расширений) " +"и совместим с Python 2 и 3, то колесо может быть \"универсальным\", подобно :" +"term:`sdist <Источниковый дистрибутив (или \"sdist\")>`." #: ../source/discussions/wheel-vs-egg.rst:33 msgid "" ":term:`Wheel` uses :pep:`PEP376-compliant <376>` ``.dist-info`` directories. " "Egg used ``.egg-info``." msgstr "" +":term:`Wheel` использует :pep:`PEP376-совместимые <376>` директории ``.dist-" +"info``. В Egg используется ``.egg-info``." #: ../source/discussions/wheel-vs-egg.rst:36 msgid "" @@ -1492,12 +1895,17 @@ msgid "" "wheel archive can indicate its compatibility with a number of Python " "language versions and implementations, ABIs, and system architectures." msgstr "" +":term:`Wheel` имеет :pep:`соглашение об именовании файлов <425>`. Один архив " +"wheel может указывать на свою совместимость с несколькими версиями и " +"реализациями языка Python, ABI и системными архитектурами." #: ../source/discussions/wheel-vs-egg.rst:40 msgid "" ":term:`Wheel` is versioned. Every wheel file contains the version of the " "wheel specification and the implementation that packaged it." msgstr "" +":term:`Wheel` является версионным. Каждый файл wheel содержит версию " +"спецификации wheel и реализацию, которая его упаковала." #: ../source/discussions/wheel-vs-egg.rst:43 msgid "" @@ -1505,6 +1913,9 @@ msgid "" "python.org/2/library/sysconfig.html#installation-paths>`_, therefore making " "it easier to convert to other formats." msgstr "" +":term:`Wheel` внутренне организовано по типу пути `sysconfig `_, что облегчает его " +"конвертацию в другие форматы." #: ../source/discussions/wheel-vs-egg.rst:47 msgid "" @@ -1512,6 +1923,9 @@ msgid "" "Read the `deprecation notice `_ for more information." msgstr "" +"Загрузки :term:`Egg` были отключены для загрузки в PyPI, согласно :pep:" +"`715`. Для получения дополнительной информации читайте уведомление о " +"депривации `_." #: ../source/discussions/wheel-vs-egg.rst:53 msgid "" @@ -1519,10 +1933,13 @@ msgid "" "format, although :ref:`this is not officially supported at this time `." msgstr "" +"В некоторых случаях колеса могут использоваться в качестве импортируемого " +"формата времени выполнения, хотя :ref:`это не поддерживается официально в " +"настоящее время `." #: ../source/flow.rst:3 msgid "The Packaging Flow" -msgstr "" +msgstr "Упаковочный поток" #: ../source/flow.rst:5 msgid "" @@ -1531,6 +1948,10 @@ msgid "" "Package Index (PyPI)`_. It is written for package publishers, who are " "assumed to be the package author." msgstr "" +"Цель этого документа - описать процесс публикации/распространения :term:" +"`распространяемого пакета <Распространяемый пакет>`, обычно в `Индекс " +"пакетов Python (PyPI)`_. Он написан для издателей пакетов, которые, как " +"предполагается, являются авторами пакетов." #: ../source/flow.rst:12 msgid "" @@ -1538,18 +1959,25 @@ msgid "" "process of preparing a simple package for release, it does not fully " "enumerate what steps and files are required, and for what purpose." msgstr "" +"Хотя в :doc:`учебнике ` рассматривается " +"процесс подготовки простого пакета к выпуску, он не полностью перечисляет, " +"какие шаги и файлы требуются и для чего." #: ../source/flow.rst:16 msgid "" "Publishing a package requires a flow from the author's source code to an end " "user's Python environment. The steps to achieve this are:" msgstr "" +"Публикация пакета требует перехода от исходного кода автора к среде Python " +"конечного пользователя. Для этого необходимо выполнить следующие шаги:" #: ../source/flow.rst:19 msgid "" "Have a source tree containing the package. This is typically a checkout from " "a version control system (VCS)." msgstr "" +"Иметь дерево исходных текстов, содержащее пакет. Обычно это проверка из " +"системы контроля версий (VCS)." #: ../source/flow.rst:22 msgid "" @@ -1558,6 +1986,10 @@ msgid "" "will be a :file:`pyproject.toml` file, maintained manually in the source " "tree." msgstr "" +"Подготовьте конфигурационный файл, описывающий метаданные пакета (имя, " +"версию и т.д.) и способ создания артефактов сборки. Для большинства пакетов " +"это будет файл :file:`pyproject.toml`, поддерживаемый вручную в дереве " +"исходных текстов." #: ../source/flow.rst:27 msgid "" @@ -1568,22 +2000,32 @@ msgid "" "build tool using the configuration file from the previous step. Often there " "is just one generic wheel for a pure Python package." msgstr "" +"Создайте артефакты сборки для отправки в службу распространения пакетов " +"(обычно PyPI); обычно это будет :term:`исходный дистрибутив (\"sdist\") " +"` и один или несколько :term:`сборных " +"дистрибутивов (\"wheels\") `. Они создаются инструментом " +"сборки с помощью конфигурационного файла, полученного на предыдущем шаге. " +"Часто для пакета чистого Python существует только одно общее колесо." #: ../source/flow.rst:35 msgid "Upload the build artifacts to the package distribution service." -msgstr "" +msgstr "Загрузите строительные артефакты в службу распределения пакетов." #: ../source/flow.rst:37 msgid "" "At that point, the package is present on the package distribution service. " "To use the package, end users must:" msgstr "" +"На этом этапе пакет присутствует в сервисе распределения пакетов. Для " +"использования пакета конечные пользователи должны:" #: ../source/flow.rst:40 msgid "" "Download one of the package's build artifacts from the package distribution " "service." msgstr "" +"Скачайте один из строительных артефактов пакета из службы распространения " +"пакетов." #: ../source/flow.rst:43 msgid "" @@ -1591,16 +2033,21 @@ msgid "" "directory. This step may involve a build/compile step which, if needed, must " "be described by the package metadata." msgstr "" +"Установите его в своей среде Python, обычно в его каталоге ``site-" +"packages``. Этот шаг может включать в себя этап сборки/компиляции, который " +"при необходимости должен быть описан пакетными метаданными." #: ../source/flow.rst:47 msgid "" "These last 2 steps are typically performed by :ref:`pip` when an end user " "runs ``pip install``." msgstr "" +"Эти два последних шага обычно выполняются :ref:`pip`, когда конечный " +"пользователь запускает ``pip install``." #: ../source/flow.rst:50 msgid "The steps above are described in more detail below." -msgstr "" +msgstr "Приведенные выше шаги более подробно описаны ниже." #: ../source/flow.rst:53 msgid "The source tree" @@ -1612,6 +2059,9 @@ msgid "" "VCS. The particular version of the code used to create the build artifacts " "will typically be a checkout based on a tag associated with the version." msgstr "" +"Источниковое дерево содержит исходный код пакета, обычно чек от VCS. " +"Конкретная версия кода, используемого для создания артефактов сборки, как " +"правило, будет проверкой на основе тега, связанного с версией." #: ../source/flow.rst:60 msgid "The configuration file" @@ -1623,6 +2073,9 @@ msgid "" "artifacts. The standard practice is to use a :file:`pyproject.toml` file in " "the `TOML format`_." msgstr "" +"Конфигурационный файл зависит от инструмента, используемого для создания " +"артефактов сборки. Стандартной практикой является использование файла :file:" +"`pyproject.toml` в формате `TOML`_." #: ../source/flow.rst:68 msgid "" @@ -1632,10 +2085,15 @@ msgid "" "`poetry`, :ref:`setuptools`, `trampolim`_, and `whey`_. Each tool's " "documentation will show what to put in the ``[build-system]`` table." msgstr "" +"Как минимум, файл :file:`pyproject.toml' нуждается в ``[build-system]`` " +"таблица с указанием вашего инструмента сборки. Имеется множество " +"инструментов для сборки, в том числе:ref:`flit`, :ref:`hatch`, :ref:`pdm`, :" +"ref:`poetry`, :ref:`setuptools', `trampolim`_ и `whey`_. Документация " +"каждого инструмента покажет, что поместить в таблицу ``[build-system]``." #: ../source/flow.rst:77 msgid "For example, here is a table for using :ref:`hatch`:" -msgstr "" +msgstr "Например, вот таблица для использования:ref:`hatch`:" #: ../source/flow.rst:85 msgid "" @@ -1646,34 +2104,53 @@ msgid "" "`pip` also acts as a frontend when it runs your build tool's backend to " "install from a source distribution." msgstr "" +"С такой таблицей в файле :file:`pyproject.toml', \":term:`frontend `\" tool like :ref:`build` может запускать выбранный вами " +"инструмент построения \":term:`backend `\" для создания " +"артефактов сборки. Ваш инструмент сборки также может предоставить свой " +"собственный фронтенд. Инструмент установки, такой как :ref:`pip'', также " +"действует в качестве фронтенда, когда он запускает предысторию вашего " +"инструмента для установки из распределения источника." #: ../source/flow.rst:94 msgid "" "The particular build tool you choose dictates what additional information is " "required in the :file:`pyproject.toml` file. For example, you might specify:" msgstr "" +"Выбранный вами инструмент сборки диктует, какая дополнительная информация " +"требуется в файле :file:`pyproject.toml`. Например, вы можете указать:" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" +"таблица ``[проект]``, содержащая проект :doc:``Основные метаданные ` (название, версия, автор и так далее)," + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" +"таблица ``[tool]``, содержащая параметры конфигурации, специфичные для " +"конкретного инструмента." #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" +"Полное руководство по настройке ``pyproject.toml'' см. в :ref:`pyproject." +"toml guide `." -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" -msgstr "" +msgstr "Создание артефактов" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "Распространение в исходном коде (sdist)" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1681,31 +2158,45 @@ msgid "" "wanting to develop your sources, and for end user systems where some local " "compilation step is required (such as a C extension)." msgstr "" +"Дистрибутив с исходным кодом содержит достаточно средств для установки " +"пакета из исходного кода в среду Python конечного пользователя. Как таковой, " +"он содержит исходный текст пакета, а также может включать тесты и " +"документацию. Они полезны для конечных пользователей, желающих разработать " +"свои исходные тексты, а также для систем конечных пользователей, где " +"требуется локальная компиляция (например, расширение C)." -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" +"Пакет :ref:`build` знает, как вызвать ваш инструмент сборки для создания " +"одного из них:" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" +"Или же ваш инструмент сборки может предоставлять собственный интерфейс для " +"создания sdist." -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" -msgstr "" +msgstr "Построенные дистрибутивы (колеса)" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " "wheel file can simply be unpacked into the ``site-packages`` directory. This " "makes the install faster and more convenient for end users." msgstr "" +"Собранный дистрибутив содержит только файлы, необходимые для среды Python " +"конечного пользователя. При установке не требуется компиляция, а файл wheel " +"можно просто распаковать в каталог ``ite-packages``. Это делает установку " +"более быстрой и удобной для конечных пользователей." -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1713,49 +2204,68 @@ msgid "" "supports. If a suitable wheel file is not available, tools like :ref:`pip` " "will fall back to installing the source distribution." msgstr "" +"Пакету на чистом Python обычно требуется только одно \"общее\" колесо. Пакет " +"с компилируемыми бинарными расширениями нуждается в колесе для каждой " +"поддерживаемой комбинации интерпретатора Python, операционной системы и " +"архитектуры процессора, которые он поддерживает. Если подходящий файл колеса " +"недоступен, такие инструменты, как :ref:`pip`, вернутся к установке " +"исходного дистрибутива." -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" +"Или же ваш инструмент сборки может предоставлять собственный интерфейс для " +"создания колеса." -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" +"По умолчанию поведение :ref:`build' состоит в том, чтобы сделать как sdist, " +"так и колесо из источника в текущем каталоге; приведенные выше примеры " +"преднамеренно конкретны." -#: ../source/flow.rst:157 -#, fuzzy +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" -msgstr "Загрузите свои дистрибутивы" +msgstr "Загрузка в службу распространения пакетов" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" +"Инструмент :ref:`twine` может загружать артефакты сборки в PyPI для " +"распространения, используя такую команду, как:" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" +"Или же ваш инструмент сборки может предоставлять собственный интерфейс для " +"загрузки." -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" -msgstr "" +msgstr "Скачать и установить" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" +"Теперь, когда пакет опубликован, конечные пользователи могут загрузить и " +"установить его в свою среду Python. Обычно это делается с помощью :ref:" +"`pip`, используя такую команду, как:" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." msgstr "" +"Конечные пользователи могут также использовать другие инструменты, такие как:" +"ref:`pipenv`, :ref:`poetry', или :ref:`pdm'." #: ../source/glossary.rst:3 msgid "Glossary" @@ -1763,17 +2273,19 @@ msgstr "Словарь терминов" #: ../source/glossary.rst:8 msgid "Binary Distribution" -msgstr "" +msgstr "Двоичное распределение" #: ../source/glossary.rst:11 msgid "" "A specific kind of :term:`Built Distribution` that contains compiled " "extensions." msgstr "" +"Особый вид :term:`Built Distribution`, содержащий скомпилированные " +"расширения." #: ../source/glossary.rst:14 msgid "Build Backend" -msgstr "" +msgstr "Создание бэкэнда" #: ../source/glossary.rst:17 msgid "" @@ -1782,6 +2294,11 @@ msgid "" "`wheel ` from it. The build is delegated to the backend by a :term:" "`frontend `. All backends offer a standardized interface." msgstr "" +"Библиотека, которая принимает дерево исходных текстов или :term:`source " +"distribution ` и собирает из него " +"исходный дистрибутив или :term:`wheel `. Сборка делегируется бэкенду " +"с помощью :term:`frontend `. Все бэкенды предлагают " +"стандартизированный интерфейс." #: ../source/glossary.rst:24 msgid "" @@ -1789,10 +2306,13 @@ msgid "" "hatchling `, :ref:`maturin`, :ref:`meson-python`, :ref:`scikit-build-" "core`, and :ref:`setuptools`." msgstr "" +"Примерами бэкендов сборки являются :ref:`flit's flit-core `, :ref:" +"`hatch's hatchling `, :ref:`maturin`, :ref:`meson-python`, :ref:" +"`scikit-build-core`, и :ref:`setuptools`." #: ../source/glossary.rst:32 msgid "Build Frontend" -msgstr "" +msgstr "Сборка фронтенда" #: ../source/glossary.rst:35 msgid "" @@ -1802,14 +2322,19 @@ msgid "" "building is delegated to each source tree's :term:`build backend `." msgstr "" +"Инструмент, который может быть запущен пользователями, который принимает " +"произвольные деревья исходных текстов или :term:`дистрибутивы исходных " +"текстов ` и собирает из них " +"дистрибутивы исходных текстов или :term:`колеса `. Собственно сборка " +"делегируется каждому дереву исходников :term:`build backend `." #: ../source/glossary.rst:42 msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." -msgstr "" +msgstr "Примерами фронтендов сборки являются :ref:`pip` и :ref:`build`." #: ../source/glossary.rst:44 msgid "Built Distribution" -msgstr "" +msgstr "Построенное распределение" #: ../source/glossary.rst:47 msgid "" @@ -1821,10 +2346,18 @@ msgid "" "not imply that Python files have to be precompiled (:term:`Wheel` " "intentionally does not include compiled Python files)." msgstr "" +"Формат :term:`Distribution <Дистрибутивный пакет>`, содержащий файлы и " +"метаданные, которые нужно только переместить в нужное место на целевой " +"системе, чтобы установить. :term:`Wheel` является таким форматом, в то время " +"как :term:`Source Distribution <Источниковый дистрибутив (или \"sdist\")>` " +"от distutil не является, так как требует шага сборки перед установкой. Этот " +"формат не подразумевает, что файлы Python должны быть предварительно " +"скомпилированы (:term:`Wheel` намеренно не включает скомпилированные файлы " +"Python)." #: ../source/glossary.rst:56 msgid "Distribution Package" -msgstr "" +msgstr "Пакет дистрибутива" #: ../source/glossary.rst:59 msgid "" @@ -1833,8 +2366,21 @@ msgid "" "to distribute a :term:`Release`. The archive file is what an end-user will " "download from the internet and install." msgstr "" +"Версионный архивный файл, содержащий Python :term:`пакеты `, :term:`модули ` и другие файлы ресурсов, которые " +"используются для распространения :term:`Release`. Архивный файл - это то, " +"что конечный пользователь скачает из интернета и установит." #: ../source/glossary.rst:64 +#, fuzzy +#| msgid "" +#| "A distribution package is more commonly referred to with the single words " +#| "\"package\" or \"distribution\", but this guide may use the expanded term " +#| "when more clarity is needed to prevent confusion with an :term:`Import " +#| "Package` (which is also commonly called a \"package\") or another kind of " +#| "distribution (e.g. a Linux distribution or the Python language " +#| "distribution), which are often referred to with the single term " +#| "\"distribution\"." msgid "" "A distribution package is more commonly referred to with the single words " "\"package\" or \"distribution\", but this guide may use the expanded term " @@ -1842,26 +2388,37 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" +"Дистрибутив чаще всего обозначается одним словом \"пакет\" или " +"\"дистрибутив\", но в данном руководстве может использоваться расширенный " +"термин, когда требуется большая ясность, чтобы избежать путаницы с :термином:" +"`импортный пакет` (который также обычно называется \"пакет\") или другим " +"видом дистрибутива (например, дистрибутив Linux или дистрибутив языка " +"Python), которые часто обозначаются одним термином \"дистрибутив\"." -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" -msgstr "" +msgstr "Яйцо" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " "Structure of Python Eggs ` and `Python " "Eggs `_" msgstr "" +"Формат :term:`Built Distribution`, введенный :ref:`setuptools`, который " +"заменяется :term:`Wheel`. Подробности см. в :doc:`Внутренняя структура " +"Python Eggs ` и `Python Eggs `_" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "Модуль расширения" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1869,12 +2426,17 @@ msgid "" "file for Python extensions on Unix, a DLL (given the .pyd extension) for " "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" +"Термин:`Модуль`, написанный на языке низкого уровня реализации Python: C/C++ " +"для Python, Java для Jython. Обычно содержится в одном динамически " +"загружаемом предварительно скомпилированном файле, например, в файле общих " +"объектов (.so) для расширений Python на Unix, DLL (с расширением .pyd) для " +"расширений Python на Windows, или в файле классов Java для расширений Jython." -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "Known Good Set (KGS, Известный хороший набор)" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1882,68 +2444,97 @@ msgid "" "used by frameworks and toolkits which are comprised of multiple individual " "distributions." msgstr "" +"Набор дистрибутивов определенных версий, совместимых друг с другом. Обычно " +"перед тем, как объявить определенный набор пакетов заведомо исправным, " +"запускается набор тестов, который проходит все проверки. Этот термин обычно " +"используется во фреймворках и наборах инструментов, которые состоят из " +"нескольких отдельных дистрибутивов." -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "Import Package (Импортируемый пакет)" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" +"Модуль Python, который может содержать другие модули или, рекурсивно, другие " +"пакеты." -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 +#, fuzzy +#| msgid "" +#| "An import package is more commonly referred to with the single word " +#| "\"package\", but this guide will use the expanded term when more clarity " +#| "is needed to prevent confusion with a :term:`Distribution Package` which " +#| "is also commonly called a \"package\"." msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" +"Импортный пакет чаще всего обозначается одним словом \"пакет\", но в данном " +"руководстве будет использоваться расширенный термин, когда требуется большая " +"ясность, чтобы избежать путаницы с :термином:`Дистрибутивный пакет`, который " +"также обычно называется \"пакет\"." -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Модуль" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" +"Базовая единица многократного использования кода в Python, существующая в " +"одном из двух типов: :термин: «чистый модуль» или :термин: «модуль " +"расширения»." -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" -msgstr "" +msgstr "Индекс пакета" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" +"Репозиторий дистрибутивов с веб-интерфейсом для автоматизации :term:`package " +"` обнаружения и потребления." -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" -msgstr "" +msgstr "Индекс на проект" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" +"Частный или иной неканонический:термин: «Индекс пакетов», обозначенный " +"конкретным:термин: «проект» как индекс, предпочтительный или необходимый для " +"решения зависимостей этого проекта." -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Проект" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" +"Библиотека, структура, сценарий, плагин, приложение или сбор данных или " +"других ресурсов, или определенная их комбинация, которая должна быть " +"упакована в :term:`Distribution `." -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1951,38 +2542,53 @@ msgid "" "something that contains a :term:`pyproject.toml`, :term:`setup.py`, or :term:" "`setup.cfg` file at the root of the project source directory." msgstr "" +"Поскольку большинство проектов создают :term:`Distributions <Дистрибутивный " +"пакет>`, используя либо :pep:`518` `build-system`, :ref:`distutils` или :ref:" +"`setuptools`, другим практичным способом определения проектов в настоящее " +"время является то, что содержит :term:`pyproject.toml`, :term:`setup.py` " +"или :term:`setup.cfg` файл в корне исходного каталога проекта." -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" "term:`Releases `, and each release may comprise one or more :term:" "`distributions `." msgstr "" +"Проекты Python должны иметь уникальные имена, которые регистрируются в :term:" +"`PyPI `. Каждый проект будет содержать один или " +"несколько :term:`Releases `, а каждый релиз может состоять из " +"одного или нескольких :term:`distributions `." -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " "to hold true. It's possible to install a distribution from the project 'foo' " "and have it provide a package importable only as 'bar'." msgstr "" +"Обратите внимание, что существует строгое правило называть проект по имени " +"пакета, который импортируется для запуска этого проекта. Однако это не " +"обязательно так. Можно установить дистрибутив из проекта 'foo' и получить от " +"него пакет, импортируемый только как 'bar'." -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" -msgstr "" +msgstr "Чистый модуль" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" +"Модуль, написанный на языке Python и содержащийся в одном файле ``.py`` (и, " +"возможно, связанных с ним файлах ``.pyc`` и/или ``.pyo``)." -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" -msgstr "" +msgstr "Python Управление по упаковке (PyPA)" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1991,61 +2597,82 @@ msgid "" "`_ and " "`the Python Discourse forum `__." msgstr "" +"PyPA - это рабочая группа, которая поддерживает множество соответствующих " +"проектов по упаковке Python. Они поддерживают сайт по адресу :doc:`pypa.io " +"`, размещают проекты на `GitHub `_ и " +"`Bitbucket `_, а также обсуждают проблемы в " +"списке рассылки `distutils-sig `_ и на форуме Python Discourse `__." -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" -msgstr "" +msgstr "Индекс пакетов Python (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" +"`PyPI `_ является стандартным :term:`Package Index` для " +"сообщества Python. Он открыт для всех разработчиков Python для потребления и " +"распространения их дистрибутивов." -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" +"`pypi.org `_ - это доменное имя для :term:`Python Package " +"Index (PyPI)`. Он заменил устаревшее доменное имя индекса, ``pypi.python." +"org``, в 2017 году. Он работает на базе :ref:`warehouse`." -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" -msgstr "" +msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" +"Инструмент-агностик:термин: файл спецификации \"Проект\". Определен в :pep:" +"`518'." -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "Выпуск" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" +"Снимок :term:`Project` в определенный момент времени, обозначаемый " +"идентификатором версии." -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " "released, it could be available in both a source distribution format and a " "Windows installer distribution format." msgstr "" +"Создание релиза может повлечь за собой публикацию нескольких :term:" +"`Distributions `. Например, если версия 1.0 проекта " +"была выпущена, она может быть доступна как в формате распределения " +"источника, так и в формате Windows." -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "Требование" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2053,24 +2680,41 @@ msgid "" "considered a \"requirement\". For more information, see the :ref:`pip:pip " "install` reference." msgstr "" +"Спецификация для устанавливаемого :term:`пакета `. :" +"ref:`pip`, рекомендуемый установщик :term:`PYPA `, допускает различные формы спецификации, которые все могут " +"считаться \"требованием\". Для получения дополнительной информации смотрите " +"ссылку :ref:`pip:pip install`." -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" -msgstr "" +msgstr "Спецификатор требований" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 +#, fuzzy +#| msgid "" +#| "A format used by :ref:`pip` to install packages from a :term:`Package " +#| "Index`. For an EBNF diagram of the format, see the `pkg_resources." +#| "Requirement `_ entry in the :ref:`setuptools` docs. For " +#| "example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +#| "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" +"Формат, используемый :ref:`pip` для установки пакетов из :term:`Package " +"Index`. Для диаграммы EBNF формата см. в `pkg_resources.Requirement `_ в :ref:`setuptools` docs. Например, \"foo>=1.3\" является " +"спецификатором требований, где \"foo\" является наименованием проекта, а " +"«>=1.3» - это:термин:`Version Specifier `" #: ../source/glossary.rst:216 msgid "Requirements File" -msgstr "" +msgstr "Требования к файлам" #: ../source/glossary.rst:219 msgid "" @@ -2078,14 +2722,17 @@ msgid "" "installed using :ref:`pip`. For more information, see the :ref:`pip` docs " "on :ref:`pip:Requirements Files`." msgstr "" +"Файл, содержащий список :term:`Requirements ` который может " +"быть установлен с помощью :ref:`pip'. Дополнительные сведения см. в :ref:" +"`pip'''' docs on :ref:`pip:Requirements Files`." #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2094,10 +2741,12 @@ msgid "" "The project specification files for :ref:`distutils` and :ref:`setuptools`. " "See also :term:`pyproject.toml`." msgstr "" +"Файлы спецификаций проекта для:ref:`distutils' и :ref:`setuptools'. См. " +"также :term:`pyproject.toml'." #: ../source/glossary.rst:230 msgid "Source Archive" -msgstr "" +msgstr "Источник Архив" #: ../source/glossary.rst:233 msgid "" @@ -2105,10 +2754,13 @@ msgid "" "creation of a :term:`Source Distribution ` or :term:`Built Distribution`." msgstr "" +"Архив, содержащий исходный код для :term:`Release`, до создания :term:" +"`Source Distribution ` или :term:`Built " +"Distribution`." #: ../source/glossary.rst:237 msgid "Source Distribution (or \"sdist\")" -msgstr "" +msgstr "Распространение исходных текстов (или \"sdist\")" #: ../source/glossary.rst:240 msgid "" @@ -2117,20 +2769,27 @@ msgid "" "source files needed for installing by a tool like :ref:`pip`, or for " "generating a :term:`Built Distribution`." msgstr "" +"A:термин: <Отметка «Distribution Package>`» (обычно сгенерированная с " +"использованием ``python -m build --sdist``), которая предоставляет " +"метаданные и основные исходные файлы, необходимые для установки с помощью " +"такого инструмента, как:ref:`pip', или для создания:term:`Built " +"Distribution'." #: ../source/glossary.rst:245 msgid "System Package" -msgstr "" +msgstr "Системный пакет" #: ../source/glossary.rst:248 msgid "" "A package provided in a format native to the operating system, e.g. an rpm " "or dpkg file." msgstr "" +"Пакет, предоставляемый в формате, имеющем отношение к операционной системе, " +"например, файл rpm или dpkg." #: ../source/glossary.rst:251 msgid "Version Specifier" -msgstr "" +msgstr "Спецификатор версии" #: ../source/glossary.rst:254 msgid "" @@ -2140,10 +2799,15 @@ msgid "" "that Python packaging currently supports. Support for this specification " "was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0." msgstr "" +"Компонент версии :термин: \" спецификатор запросов \" . Например, \">=1.3\" " +"части \"foo>=1.3\". Прочтите :ref:`Version спецификатор ` для полного описания спецификаторов, которые Python в " +"настоящее время поддерживаются. Поддержка этой спецификации была реализована " +"в :ref:`setuptools` v8.0 и :ref:`pip` v6.0." #: ../source/glossary.rst:259 msgid "Virtual Environment" -msgstr "" +msgstr "Виртуальная среда" #: ../source/glossary.rst:262 msgid "" @@ -2152,10 +2816,14 @@ msgid "" "more information, see the section on :ref:`Creating and using Virtual " "Environments`." msgstr "" +"Изолированная среда Python, которая позволяет устанавливать пакеты для " +"использования конкретным приложением, а не устанавливать их в масштабах всей " +"системы. Для получения дополнительной информации см. раздел :ref:`Создание и " +"использование виртуальных сред`." #: ../source/glossary.rst:266 msgid "Wheel" -msgstr "" +msgstr "Колесо" #: ../source/glossary.rst:269 msgid "" @@ -2164,10 +2832,14 @@ msgid "" "intended to replace the :term:`Egg` format. Wheel is currently supported " "by :ref:`pip`." msgstr "" +"Формат :term:`Built Distribution`, введенный официальной спецификацией :doc:" +"`standard specification `, " +"который призван заменить формат :term:`Egg`. В настоящее время Wheel " +"поддерживается :ref:`pip`." #: ../source/glossary.rst:274 msgid "Working Set" -msgstr "" +msgstr "Рабочая группа" #: ../source/glossary.rst:277 msgid "" @@ -2176,6 +2848,10 @@ msgid "" "At most, one :term:`Distribution ` for a project is " "possible in a working set." msgstr "" +"Коллекция :term:`дистрибутивов `, доступных для " +"импорта. Это дистрибутивы, которые находятся в переменной `sys.path. В " +"рабочем наборе возможен максимум один :term:`Distribution ` для проекта." #: ../source/guides/analyzing-pypi-package-downloads.rst:3 msgid "Analyzing PyPI package downloads" @@ -2188,6 +2864,10 @@ msgid "" "example, you can use it to discover the distribution of Python versions used " "to download a package." msgstr "" +"Этот раздел охватывает, как использовать публичный набор данных статистики " +"загрузки PyPI, чтобы узнать больше о загрузках пакета (или пакетов), " +"размещенного на PyPI. Например, вы можете использовать его для обнаружения " +"распространения версий Python, используемых для загрузки пакета." #: ../source/guides/analyzing-pypi-package-downloads.rst:12 #: ../source/guides/supporting-windows-using-appveyor.rst:17 @@ -2196,7 +2876,7 @@ msgstr "Фон" #: ../source/guides/analyzing-pypi-package-downloads.rst:14 msgid "PyPI does not display download statistics for a number of reasons: [#]_" -msgstr "" +msgstr "PyPI не отображает статистику загрузки по ряду причин: [#]_" #: ../source/guides/analyzing-pypi-package-downloads.rst:16 msgid "" @@ -2205,21 +2885,29 @@ msgid "" "which are heavily cached, would require invalidating the cache more often, " "and reduce the overall effectiveness of the cache." msgstr "" +"**Неэффективно работать с сетью распространения контента (CDN):** Загрузка " +"статистики меняется постоянно. Включение их в страницы проекта, которые " +"сильно кэшируются, потребует более частой аннулирования кэша и снижения " +"общей эффективности кэша." #: ../source/guides/analyzing-pypi-package-downloads.rst:21 msgid "" "**Highly inaccurate:** A number of things prevent the download counts from " "being accurate, some of which include:" msgstr "" +"**Очень неточно:** Некоторые вещи не позволяют считать загрузку точной, " +"некоторые из которых включают:" #: ../source/guides/analyzing-pypi-package-downloads.rst:24 msgid "``pip``'s download cache (lowers download counts)" -msgstr "" +msgstr "``pip`` кэш загрузки (считывает количество загрузок)" #: ../source/guides/analyzing-pypi-package-downloads.rst:25 msgid "" "Internal or unofficial mirrors (can both raise or lower download counts)" msgstr "" +"Внутренние или неофициальные зеркала (могут как поднять, так и снизить " +"количество загрузок)" #: ../source/guides/analyzing-pypi-package-downloads.rst:26 msgid "Packages not hosted on PyPI (for comparisons sake)" @@ -2230,10 +2918,13 @@ msgid "" "Unofficial scripts or attempts at download count inflation (raises download " "counts)" msgstr "" +"Неофициальные скрипты или попытки скачать подсчет инфляции (изобличает " +"количество загрузок)" #: ../source/guides/analyzing-pypi-package-downloads.rst:29 msgid "Known historical data quality issues (lowers download counts)" msgstr "" +"Известные исторические проблемы качества данных (низкие числа загрузок)" #: ../source/guides/analyzing-pypi-package-downloads.rst:31 msgid "" @@ -2241,17 +2932,23 @@ msgid "" "lot doesn't mean it's good; Similarly just because a project hasn't been " "downloaded a lot doesn't mean it's bad!" msgstr "" +"** Не особенно полезно:** То, что проект был загружен очень много, не " +"означает, что он хорош; Точно так же только потому, что проект не был " +"загружен много, не означает, что это плохо!" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" +"Короче говоря, поскольку его стоимость является низкой по различным " +"причинам, а компромиссы, необходимые для его работы, высоки, это не было " +"эффективным использованием ограниченных ресурсов." #: ../source/guides/analyzing-pypi-package-downloads.rst:40 msgid "Public dataset" -msgstr "" +msgstr "Набор данных" #: ../source/guides/analyzing-pypi-package-downloads.rst:42 msgid "" @@ -2259,10 +2956,13 @@ msgid "" "cloud-function/>`__ streams download logs from PyPI to `Google BigQuery`_ " "[#]_, where they are stored as a public dataset." msgstr "" +"`__ потоков загружает " +"журналы от PyPI до `Google BigQuery`_ [#]_, где они хранятся в виде набора " +"общедоступных данных." #: ../source/guides/analyzing-pypi-package-downloads.rst:47 msgid "Getting set up" -msgstr "" +msgstr "Подготовка к работе" #: ../source/guides/analyzing-pypi-package-downloads.rst:49 msgid "" @@ -2273,10 +2973,15 @@ msgid "" "`__" msgstr "" +"Для того, чтобы использовать `Google BigQuery`_ для запроса 'публичной PyPI " +"загрузки статистических данных `_, вам понадобится учетная запись Google и " +"включить API BigQuery в проект Google Cloud Platform. `__" #: ../source/guides/analyzing-pypi-package-downloads.rst:55 msgid "Navigate to the `BigQuery web UI`_." -msgstr "" +msgstr "Перейдите к `BigQuery веб-UI`_." #: ../source/guides/analyzing-pypi-package-downloads.rst:56 msgid "Create a new project." @@ -2287,6 +2992,8 @@ msgid "" "Enable the `BigQuery API `__." msgstr "" +"Включить `BigQuery API `__." #: ../source/guides/analyzing-pypi-package-downloads.rst:60 msgid "" @@ -2294,10 +3001,13 @@ msgid "" "out the `BigQuery quickstart guide `__." msgstr "" +"Для более подробных инструкций о том, как начать работу с BigQuery, " +"ознакомьтесь с `BigQuery Руководством по ускоренному запуску `__." #: ../source/guides/analyzing-pypi-package-downloads.rst:66 msgid "Data schema" -msgstr "" +msgstr "Схема данных" #: ../source/guides/analyzing-pypi-package-downloads.rst:68 msgid "" @@ -2307,20 +3017,25 @@ msgid "" "schema `__ include:" msgstr "" +"Linehaul пишет запись в таблице ``bigquery-public-data.pypi.file_downloads`` " +"для каждой загрузки. В таблице содержится информация о том, какой файл был " +"загружен и как он был загружен. Некоторые полезные столбцы из «табличной " +"схемы `__ включить:" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 msgid "Column" msgstr "Колонка" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Описание" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Примеры" @@ -2330,7 +3045,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:77 msgid "Date and time" -msgstr "" +msgstr "Дата и время" #: ../source/guides/analyzing-pypi-package-downloads.rst:77 msgid "``2020-03-09 00:33:03 UTC``" @@ -2393,6 +3108,7 @@ msgid "" "Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " "button." msgstr "" +"Запустить запросы в `BigQuery веб-UI`_, нажав на кнопку \"Compose request\"." #: ../source/guides/analyzing-pypi-package-downloads.rst:94 msgid "" @@ -2400,6 +3116,9 @@ msgid "" "cost of queries. These example queries analyze downloads from recent history " "by filtering on the ``timestamp`` column." msgstr "" +"Обратите внимание, что строки хранятся в разделенной таблице, что помогает " +"ограничить стоимость запросов. Эти примеры запросов анализируют загрузки из " +"недавней истории путем фильтрации на столбце ``timestamp``." #: ../source/guides/analyzing-pypi-package-downloads.rst:99 msgid "Counting package downloads" @@ -2410,6 +3129,8 @@ msgid "" "The following query counts the total number of downloads for the project " "\"pytest\"." msgstr "" +"В следующем запросе учитывается общее количество загрузок для проекта " +"«pytest." #: ../source/guides/analyzing-pypi-package-downloads.rst:116 #: ../source/guides/analyzing-pypi-package-downloads.rst:137 @@ -2427,6 +3148,8 @@ msgid "" "To count downloads from pip only, filter on the ``details.installer.name`` " "column." msgstr "" +"Чтобы подсчитать загрузки только из pip, отфильтруйте столбец ``details." +"installer.name``." #: ../source/guides/analyzing-pypi-package-downloads.rst:139 msgid "24334215" @@ -2441,6 +3164,9 @@ msgid "" "To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " "filtering by this column reduces corresponding costs." msgstr "" +"Для группировки по месячным загрузкам используйте функцию " +"``TIMESTAMP_TRUNC``. Также фильтрация по этому столбцу снижает " +"соответствующие расходы." #: ../source/guides/analyzing-pypi-package-downloads.rst:165 msgid "month" @@ -2460,7 +3186,7 @@ msgstr "2344692" #: ../source/guides/analyzing-pypi-package-downloads.rst:169 msgid "2017-12-01" -msgstr "" +msgstr "2017-12-01" #: ../source/guides/analyzing-pypi-package-downloads.rst:171 msgid "1730398" @@ -2468,7 +3194,7 @@ msgstr "1730398" #: ../source/guides/analyzing-pypi-package-downloads.rst:171 msgid "2017-11-01" -msgstr "" +msgstr "2017-11-01" #: ../source/guides/analyzing-pypi-package-downloads.rst:173 msgid "2047310" @@ -2476,7 +3202,7 @@ msgstr "2047310" #: ../source/guides/analyzing-pypi-package-downloads.rst:173 msgid "2017-10-01" -msgstr "" +msgstr "2017-10-01" #: ../source/guides/analyzing-pypi-package-downloads.rst:175 msgid "1744443" @@ -2484,7 +3210,7 @@ msgstr "1744443" #: ../source/guides/analyzing-pypi-package-downloads.rst:175 msgid "2017-09-01" -msgstr "" +msgstr "2017-09-01" #: ../source/guides/analyzing-pypi-package-downloads.rst:177 msgid "1916952" @@ -2492,17 +3218,19 @@ msgstr "1916952" #: ../source/guides/analyzing-pypi-package-downloads.rst:177 msgid "2017-08-01" -msgstr "" +msgstr "2017-08-01" #: ../source/guides/analyzing-pypi-package-downloads.rst:181 msgid "Python versions over time" -msgstr "" +msgstr "Python версии с течением времени" #: ../source/guides/analyzing-pypi-package-downloads.rst:183 msgid "" "Extract the Python version from the ``details.python`` column. Warning: This " "query processes over 500 GB of data." msgstr "" +"Исключить Python версию из колонки ``details.python``. Предупреждение: Этот " +"запрос обрабатывает 500 ГБ данных." #: ../source/guides/analyzing-pypi-package-downloads.rst:202 msgid "python" @@ -2510,35 +3238,35 @@ msgstr "python" #: ../source/guides/analyzing-pypi-package-downloads.rst:204 msgid "3.7" -msgstr "" +msgstr "3.7" #: ../source/guides/analyzing-pypi-package-downloads.rst:204 msgid "18051328726" -msgstr "" +msgstr "18051328726" #: ../source/guides/analyzing-pypi-package-downloads.rst:206 msgid "3.6" -msgstr "" +msgstr "3.6" #: ../source/guides/analyzing-pypi-package-downloads.rst:206 msgid "9635067203" -msgstr "" +msgstr "9635067203" #: ../source/guides/analyzing-pypi-package-downloads.rst:208 msgid "3.8" -msgstr "" +msgstr "3.8" #: ../source/guides/analyzing-pypi-package-downloads.rst:208 msgid "7781904681" -msgstr "" +msgstr "7781904681" #: ../source/guides/analyzing-pypi-package-downloads.rst:210 msgid "2.7" -msgstr "" +msgstr "2.7" #: ../source/guides/analyzing-pypi-package-downloads.rst:210 msgid "6381252241" -msgstr "" +msgstr "6381252241" #: ../source/guides/analyzing-pypi-package-downloads.rst:212 msgid "null" @@ -2546,19 +3274,19 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:212 msgid "2026630299" -msgstr "" +msgstr "2026630299" #: ../source/guides/analyzing-pypi-package-downloads.rst:214 msgid "3.5" -msgstr "" +msgstr "3.5" #: ../source/guides/analyzing-pypi-package-downloads.rst:214 msgid "1894153540" -msgstr "" +msgstr "1894153540" #: ../source/guides/analyzing-pypi-package-downloads.rst:219 msgid "Getting absolute links to artifacts" -msgstr "" +msgstr "Получение абсолютной связи с артефактами" #: ../source/guides/analyzing-pypi-package-downloads.rst:221 msgid "" @@ -2567,16 +3295,22 @@ msgid "" "release has been deleted from PyPI. The metadata table includes the ``path`` " "column, which includes the hash and artifact filename." msgstr "" +"Иногда полезно иметь возможность получить абсолютные ссылки на загрузку " +"артефактов из PyPI на основе их хэшей, например, если определенный проект " +"или релиз был удален из PyPI. В таблице метаданных есть колонка ``path'', " +"которая включает в себя хэш и имя файла артефакта." #: ../source/guides/analyzing-pypi-package-downloads.rst:227 msgid "" "The URL generated here is not guaranteed to be stable, but currently aligns " "with the URL where PyPI artifacts are hosted." msgstr "" +"Не гарантируется, что сгенерированный здесь URL будет стабильным, но в " +"настоящее время он совпадает с URL, на котором размещены артефакты PyPI." #: ../source/guides/analyzing-pypi-package-downloads.rst:240 msgid "url" -msgstr "" +msgstr "url" #: ../source/guides/analyzing-pypi-package-downloads.rst:242 msgid "" @@ -2584,6 +3318,9 @@ msgid "" "eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" "sampleproject-1.2.0.tar.gz" msgstr "" +"https://files.pythonhosted.org/packages/" +"eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" #: ../source/guides/analyzing-pypi-package-downloads.rst:244 msgid "" @@ -2591,6 +3328,9 @@ msgid "" "packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" "sampleproject_nomura-1.2.0-py2.py3-none-any.whl" msgstr "" +"https://files.pythonhosted.org/" +"packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" #: ../source/guides/analyzing-pypi-package-downloads.rst:246 msgid "" @@ -2598,6 +3338,9 @@ msgid "" "packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" "sampleproject_nomura-1.2.0.tar.gz" msgstr "" +"https://files.pythonhosted.org/" +"packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" #: ../source/guides/analyzing-pypi-package-downloads.rst:248 msgid "" @@ -2605,6 +3348,9 @@ msgid "" "e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" "sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" #: ../source/guides/analyzing-pypi-package-downloads.rst:250 msgid "" @@ -2612,10 +3358,13 @@ msgid "" "packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" "sampleproject-1.3.1.tar.gz" msgstr "" +"https://files.pythonhosted.org/" +"packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" #: ../source/guides/analyzing-pypi-package-downloads.rst:255 msgid "Caveats" -msgstr "" +msgstr "Оговорки" #: ../source/guides/analyzing-pypi-package-downloads.rst:257 msgid "" @@ -2625,6 +3374,11 @@ msgid "" "accurate (e.g. the percentage of Python 2 vs. Python 3 downloads) but total " "numbers are lower than actual by an order of magnitude." msgstr "" +"В дополнение к предостережениям, перечисленным выше, Linehaul страдает от " +"ошибки, из-за которой он значительно занижает статистику загрузок до 26 июля " +"2018 года. Количество загрузок до этой даты пропорционально точно (например, " +"процентное соотношение загрузок Python 2 и Python 3), но общее количество на " +"порядок ниже фактического." #: ../source/guides/analyzing-pypi-package-downloads.rst:265 msgid "Additional tools" @@ -2635,10 +3389,12 @@ msgid "" "Besides using the BigQuery console, there are some additional tools which " "may be useful when analyzing download statistics." msgstr "" +"Помимо использования консоли BigQuery, есть несколько дополнительных " +"инструментов, которые могут быть полезны при анализе статистики загрузок." #: ../source/guides/analyzing-pypi-package-downloads.rst:271 msgid "``google-cloud-bigquery``" -msgstr "" +msgstr "``google-cloud-bigquery``" #: ../source/guides/analyzing-pypi-package-downloads.rst:273 msgid "" @@ -2646,10 +3402,13 @@ msgid "" "programmatically via the BigQuery API and the `google-cloud-bigquery`_ " "project, the official Python client library for BigQuery." msgstr "" +"Вы также можете получить доступ к публичному набору данных статистики " +"загрузок PyPI программным путем через BigQuery API и проект `google-cloud-" +"bigquery`_, официальную клиентскую библиотеку Python для BigQuery." #: ../source/guides/analyzing-pypi-package-downloads.rst:301 msgid "``pypinfo``" -msgstr "" +msgstr "``pypinfo``" #: ../source/guides/analyzing-pypi-package-downloads.rst:303 msgid "" @@ -2657,6 +3416,10 @@ msgid "" "can generate several useful queries. For example, you can query the total " "number of download for a package with the command ``pypinfo package_name``." msgstr "" +"`pypinfo`_ - это инструмент командной строки, который предоставляет доступ к " +"набору данных и может генерировать несколько полезных запросов. Например, вы " +"можете запросить общее количество загрузок для пакета с помощью команды " +"``pypinfo package_name``." #: ../source/guides/analyzing-pypi-package-downloads.rst:307 msgid "Install `pypinfo`_ using pip." @@ -2664,34 +3427,39 @@ msgstr "Установите `pypinfo`_ через :program:`pip`." #: ../source/guides/analyzing-pypi-package-downloads.rst:313 msgid "Usage:" -msgstr "" +msgstr "Использование:" #: ../source/guides/analyzing-pypi-package-downloads.rst:329 msgid "``pandas-gbq``" -msgstr "" +msgstr "``pandas-gbq``" #: ../source/guides/analyzing-pypi-package-downloads.rst:331 msgid "" "The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." msgstr "" +"Проект `pandas-gbq`_ позволяет получать доступ к результатам запросов через " +"`Pandas`_." #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" -msgstr "" +msgstr "Ссылка" #: ../source/guides/analyzing-pypi-package-downloads.rst:337 msgid "" "`PyPI Download Counts deprecation email `__" msgstr "" +"`PyPI Скачать Counts deprecation email `__" #: ../source/guides/analyzing-pypi-package-downloads.rst:338 msgid "" "`PyPI BigQuery dataset announcement email `__" msgstr "" +"Сообщение об анонсе набора данных PyPI BigQuery по электронной почте " +"`__" #: ../source/guides/creating-and-discovering-plugins.rst:3 msgid "Creating and discovering plugins" @@ -2704,10 +3472,16 @@ msgid "" "packages can be separately distributed, your application or library may want " "to automatically **discover** all of the plugins available." msgstr "" +"Часто при создании приложений или библиотек на Python вы хотите иметь " +"возможность предоставлять настройки или дополнительные возможности с помощью " +"**плагинов**. Поскольку пакеты Python могут распространяться отдельно, ваше " +"приложение или библиотека могут захотеть автоматически **обнаружить** все " +"доступные плагины." #: ../source/guides/creating-and-discovering-plugins.rst:10 msgid "There are three major approaches to doing automatic plugin discovery:" msgstr "" +"Существует три основных подхода к автоматическому обнаружению плагинов:" #: ../source/guides/creating-and-discovering-plugins.rst:12 msgid "`Using naming convention`_." @@ -2733,12 +3507,19 @@ msgid "" "uses the naming convention ``flask_{plugin_name}``. If you wanted to " "automatically discover all of the Flask plugins installed:" msgstr "" +"Если все плагины вашего приложения имеют одинаковые имена, вы можете " +"использовать :func:`pkgutil.iter_modules` для поиска всех модулей верхнего " +"уровня, которые соответствуют этому соглашению. Например, `Flask`_ " +"использует соглашение об именовании ``flask_{plugin_name}``. Если вы хотите " +"автоматически обнаружить все установленные плагины Flask:" #: ../source/guides/creating-and-discovering-plugins.rst:38 msgid "" "If you had both the `Flask-SQLAlchemy`_ and `Flask-Talisman`_ plugins " "installed then ``discovered_plugins`` would be:" msgstr "" +"Если у вас установлены оба плагина `Flask-SQLAlchemy`_ и `Flask-Talisman`_, " +"то ``discovered_plugins`` будет иметь вид:" #: ../source/guides/creating-and-discovering-plugins.rst:48 msgid "" @@ -2746,6 +3527,10 @@ msgid "" "Package Index's :ref:`simple repository API ` for all " "packages that conform to your naming convention." msgstr "" +"Использование соглашения об именовании для плагинов также позволяет " +"запрашивать у Python Package Index :ref:`simple repository API ` все пакеты, которые соответствуют вашему соглашению об " +"именовании." #: ../source/guides/creating-and-discovering-plugins.rst:58 msgid "Using namespace packages" @@ -2761,6 +3546,14 @@ msgid "" "installed, you can use :func:`pkgutil.iter_modules` to discover all modules " "and packages installed under that namespace:" msgstr "" +":doc:`Пакеты пространства имен <пакеты-пространства имен>` могут быть " +"использованы для обеспечения соглашения о том, где размещать плагины, а " +"также обеспечивают способ обнаружения. Например, если вы сделаете подпакет " +"``myapp.plugins`` пакетом пространства имен, то другие :term:``дистрибутивы " +"`` смогут предоставлять модули и пакеты для этого " +"пространства имен. После установки вы можете использовать :func:`pkgutil." +"iter_modules` для обнаружения всех модулей и пакетов, установленных под этим " +"пространством имен:" #: ../source/guides/creating-and-discovering-plugins.rst:88 msgid "" @@ -2770,6 +3563,11 @@ msgid "" "``myapp.plugins.a`` and ``myapp.plugins.b`` then ``discovered_plugins`` in " "this case would be:" msgstr "" +"Указание ``myapp.plugins.__path__`` в :func:`~pkgutil.iter_modules`` " +"заставляет его искать только те модули, которые находятся непосредственно в " +"этом пространстве имен. Например, если у вас установлены дистрибутивы, " +"предоставляющие модули ``myapp.plugins.a`` и ``myapp.plugins.b``, то " +"``discovered_plugins`` в этом случае будет:" #: ../source/guides/creating-and-discovering-plugins.rst:100 msgid "" @@ -2787,6 +3585,19 @@ msgid "" "will need to explicitly pass a list of packages to :func:`setup`'s " "``packages`` argument instead of using :func:`setuptools.find_packages`." msgstr "" +"В этом примере в качестве пакета пространства имен используется подпакет " +"(``myapp.plugins``), но можно также использовать для этой цели пакет " +"верхнего уровня (например, ``myapp_plugins``). Выбор пространства имен - это " +"вопрос предпочтений, но не рекомендуется делать основной пакет верхнего " +"уровня вашего проекта (``myapp`` в данном случае) пакетом пространства имен " +"для плагинов, так как один плохой плагин может привести к поломке всего " +"пространства имен, что в свою очередь сделает ваш проект неимпортируемым. " +"Чтобы подход \"namespace sub-package\" работал, пакеты плагинов должны " +"опускать :file:`__init__.py` для каталога пакета верхнего уровня (``myapp`` " +"в данном случае) и включать стиль namespace-package :file:`__init__.py` в " +"каталог namespace sub-package (``myapp/plugins``). Это также означает, что " +"плагины должны будут явно передавать список пакетов в аргумент ``packages`` " +"в :func:`setup``, а не использовать :func:`setuptools.find_packages``." #: ../source/guides/creating-and-discovering-plugins.rst:114 msgid "" @@ -2795,6 +3606,10 @@ msgid "" "namespace-packages` documentation and clearly document which approach is " "preferred for plugins to your project." msgstr "" +"Пакеты пространства имен - сложная функция, и существует несколько различных " +"способов их создания. Настоятельно рекомендуется прочитать документацию :doc:" +"`packaging-namespace-packages` и четко документировать, какой подход " +"предпочтителен для плагинов вашего проекта." #: ../source/guides/creating-and-discovering-plugins.rst:122 msgid "Using package metadata" @@ -2807,12 +3622,18 @@ msgid "" "plugin. Another package supporting this kind of plugin can use the metadata " "to discover that plugin." msgstr "" +"Пакеты могут иметь метаданные для плагинов, описанные в :ref:`entry-points`. " +"Указывая их, пакет сообщает, что он содержит определенный тип плагина. " +"Другой пакет, поддерживающий этот тип плагина, может использовать метаданные " +"для обнаружения этого плагина." #: ../source/guides/creating-and-discovering-plugins.rst:128 msgid "" "For example if you have a package named ``myapp-plugin-a`` and it includes " "the following in its ``pyproject.toml``:" msgstr "" +"Например, если у вас есть пакет с именем ``myapp-plugin-a`` и он включает " +"следующее в свой ``pyproject.toml``:" #: ../source/guides/creating-and-discovering-plugins.rst:136 msgid "" @@ -2820,18 +3641,25 @@ msgid "" "func:`importlib.metadata.entry_points` (or the backport_ " "``importlib_metadata >= 3.6`` for Python 3.6-3.9):" msgstr "" +"Затем вы можете обнаружить и загрузить все зарегистрированные точки входа, " +"используя :func:`importlib.metadata.entry_points` (или backport_ " +"``importlib_metadata >= 3.6`` для Python 3.6-3.9):" #: ../source/guides/creating-and-discovering-plugins.rst:151 msgid "" "In this example, ``discovered_plugins`` would be a collection of type :class:" "`importlib.metadata.EntryPoint`:" msgstr "" +"В этом примере ``discovered_plugins`` будет коллекцией типа :class:" +"`importlib.metadata.EntryPoint``:" #: ../source/guides/creating-and-discovering-plugins.rst:160 msgid "" "Now the module of your choice can be imported by executing " "``discovered_plugins['a'].load()``." msgstr "" +"Теперь выбранный вами модуль можно импортировать, выполнив команду " +"``discovered_plugins['a'].load()``." #: ../source/guides/creating-and-discovering-plugins.rst:163 msgid "" @@ -2839,6 +3667,9 @@ msgid "" "has a lot of options. It's recommended to read over the entire section on :" "doc:`entry points ` ." msgstr "" +"Спецификация ``точки входа`` в :file:`setup.py` довольно гибкая и имеет " +"множество опций. Рекомендуется прочитать весь раздел по :doc:``точкам входа " +"` ." #: ../source/guides/creating-and-discovering-plugins.rst:167 msgid "" @@ -2846,12 +3677,23 @@ msgid "" "library/importlib.metadata>`, most packaging tools other than setuptools " "provide support for defining entry points." msgstr "" +"Поскольку эта спецификация является частью :doc:`стандартной библиотеки " +"`, большинство инструментов упаковки, " +"кроме setuptools, обеспечивают поддержку определения точек входа." #: ../source/guides/distributing-packages-using-setuptools.rst:5 msgid "Packaging and distributing projects" msgstr "Упаковка и распространение проектов" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "Устаревший" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2859,27 +3701,40 @@ msgid "" "assumes that you are already familiar with the contents of the :doc:`/" "tutorials/installing-packages` page." msgstr "" +"В этом разделе рассматриваются некоторые дополнительные детали по настройке, " +"упаковке и распространению проектов Python с помощью ``setuptools``, которые " +"не были рассмотрены во вводном руководстве в :doc:`/tutorials/packaging-" +"projects``. При этом предполагается, что вы уже знакомы с содержанием " +"страницы :doc:`/tutorials/installing-packages`." -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" +"Этот раздел *не* ставит целью охватить лучшие практики разработки проектов " +"на Python в целом. Например, в нем нет руководства или рекомендаций по " +"инструментам для контроля версий, документации или тестирования." -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " "note that some advisory content there may be outdated. In the event of " "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" +"Дополнительные справочные материалы см. в :std:doc:`Building and " +"Distributing Packages ` в :ref:`setuptools` " +"docs, но учтите, что некоторые рекомендации там могут быть устаревшими. В " +"случае возникновения противоречий отдавайте предпочтение советам в " +"руководстве пользователя по упаковке Python." -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "Требования к упаковке и распространению" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." @@ -2887,38 +3742,45 @@ msgstr "" "Во-первых, убедитесь, что вы уже выполнили :ref:`требования к установке " "пакетов `." -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "Установите «twine» [1]_:" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" +"Он понадобится для загрузки вашего проекта :term:`distributions " +"<Дистрибутивный пакет>` в :term:`PyPI <Индекс пакетов Python (PyPI)>` (см. :" +"ref:`ниже <Загрузка проекта в PyPI>`)." -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "Настройка вашего проекта" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "Исходные файлы" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_ " "in the `PyPA sample project `_." msgstr "" +"Наиболее важным файлом является :file:`setup.py`, который существует в корне " +"каталога вашего проекта. Для примера смотрите `setup.py `_ " +"в проекте-образце PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "Файл :file:`setup.py` выполняет две основные функции:" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2926,27 +3788,40 @@ msgid "" "of your project are defined. The most relevant arguments are explained in :" "ref:`the section below `." msgstr "" +"Это файл, в котором настраиваются различные аспекты вашего проекта. Главная " +"особенность :file:`setup.py` заключается в том, что он содержит глобальную " +"функцию ``setup()``. Ключевые слова-аргументы этой функции определяют " +"конкретные детали вашего проекта. Наиболее важные аргументы описаны в :ref:" +"`разделе ниже `." -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" +"Это интерфейс командной строки для запуска различных команд, связанных с " +"задачами упаковки. Чтобы получить список доступных команд, выполните команду " +"``python3 setup.py --help-commands``." -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" +":file:`setup.cfg` - это ini-файл, содержащий параметры по умолчанию для " +"команд :file:`setup.py`. Для примера смотрите файл `setup.cfg `_ в проекте-образце `PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rst / README.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText `_ are supported as well (look at ``setup()``'s :ref:" "`long_description_content_type ` argument)." msgstr "" +"Все проекты должны содержать файл readme, в котором описывается цель " +"проекта. Наиболее распространенным форматом является `reStructuredText " +"`_ с расширением \"rst\", хотя это " +"не является обязательным условием; также поддерживаются различные варианты " +"`Markdown `_ (посмотрите на " +"аргумент ``setup()`` :ref:`long_description_content_type `)." -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" +"Для примера смотрите `README.md `_ из проекта-образца `PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2973,37 +3857,53 @@ msgid "" "don't need to list your readme file in :file:`MANIFEST.in`. Otherwise, " "include it to be explicit." msgstr "" +"В проектах, использующих :ref:`setuptools` 0.6.27+, стандартные файлы readme " +"(:file:`README.rst`, :file:`README.txt` или :file:`README`) по умолчанию " +"включены в дистрибутивы исходных текстов. Встроенная библиотека :ref:" +"`distutils` перенимает это поведение начиная с Python 3.7. Кроме того, :ref:" +"`setuptools` 36.4.0+ будет включать :file:`README.md`, если он будет найден. " +"Если вы используете setuptools, вам не нужно указывать свой файл readme в :" +"file:`MANIFEST.in`. В противном случае включите его в явном виде." -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " "on writing a :file:`MANIFEST.in` file, including a list of what's included " "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" +"Файл :file:`MANIFEST.in` необходим, когда вам нужно упаковать дополнительные " +"файлы, которые не включены автоматически в дистрибутив. Подробнее о " +"написании файла :file:`MANIFEST.in`, включая список того, что включается по " +"умолчанию, смотрите в разделе \":ref:`Using MANIFEST.in`\"." -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " "its manifest file, since all the necessary files have been included by :ref:" "`setuptools` 43.0.0 and newer." msgstr "" +"Однако вы можете не использовать :file:`MANIFEST.in`. Для примера, проект " +"примера `PyPA `_ удалил свой файл " +"манифеста, так как все необходимые файлы были включены в :ref:`setuptools` " +"43.0.0 и новее." -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" +":file:`MANIFEST.in' не влияет на бинарные дистрибутивы, такие как колеса." -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3012,258 +3912,99 @@ msgid "" "as `GitHub's Choose a License `_ or consult a " "lawyer." msgstr "" +"Каждый пакет должен содержать файл лицензии с подробным описанием условий " +"распространения. Во многих юрисдикциях пакеты без явной лицензии не могут " +"быть законно использованы или распространены кем-либо, кроме " +"правообладателя. Если вы не уверены, какую лицензию выбрать, вы можете " +"воспользоваться такими ресурсами, как `GitHub's Choose a License `_ или проконсультироваться с юристом." -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" +"Для примера смотрите `LICENSE.txt `_ из проекта-образца `PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "<ваш пакет>" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" +"Хотя это и не обязательно, наиболее распространенной практикой является " +"включение ваших модулей и пакетов Python в один пакет верхнего уровня, " +"который имеет то же :ref:`имя `, что и ваш проект, или что-то " +"очень близкое." -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" +"В качестве примера можно привести пакет `sample `_, который входит в состав проекта-" +"образца PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "Аргументы ``setup()``" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" +"Как уже говорилось выше, главная особенность :file:`setup.py` заключается в " +"том, что он содержит глобальную функцию ``setup()``. Ключевые слова-" +"аргументы этой функции определяют конкретные детали вашего проекта." -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``name``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" +"Некоторые из них временно описаны ниже, пока информация о них не будет " +"перенесена в другое место. Полный список можно найти :doc:`в документации по " +"setuptools `." -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" +"Большинство приведенных фрагментов взяты из файла `setup.py `_, содержащегося в проекте-образце `PyPA `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +#, fuzzy msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" +"Дополнительные сведения о том, как использовать версии для передачи " +"информации о совместимости пользователям, см. в :ref:`Выбор схемы " +"версионирования`." -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -#, fuzzy -msgid "``author``" -msgstr "Автор" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" -msgstr "" +msgstr "``пакеты``" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3272,81 +4013,57 @@ msgid "" "packages. Use the ``exclude`` keyword argument to omit packages that are " "not intended to be released and installed." msgstr "" +"Установите ``packages`` в список всех :term:`packages ` в " +"вашем проекте, включая их подпакеты, подсубпакеты и т.д. Хотя пакеты можно " +"перечислить вручную, ``setuptools.find_packages()`` находит их " +"автоматически. Используйте ключевой аргумент ``include`` для поиска только " +"заданных пакетов. Используйте ключевой аргумент ``exclude`` для исключения " +"пакетов, которые не предназначены для выпуска и установки." -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +#, fuzzy msgid "``py_modules``" -msgstr "" +msgstr "``py_modules``" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" +"Если ваш проект содержит однофайловые модули Python, которые не являются " +"частью пакета, установите ``py_modules`` в список имен модулей (за вычетом " +"расширения ``.py``), чтобы :ref:`setuptools`` узнал о них." -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 #, fuzzy msgid "``install_requires``" msgstr "install_requires" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" +"\"install_requires\" следует использовать, чтобы указать, какие зависимости " +"минимально необходимы проекту для запуска. Когда проект устанавливается с " +"помощью :ref:`pip`, именно эта спецификация используется для установки его " +"зависимостей." -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" +"Подробнее об использовании \"install_requires\" смотрите :ref:" +"`install_requires vs Requirements files`." -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -#, fuzzy -msgid "``python_requires``" -msgstr "python_requires" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "И так далее." - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "``package_data``" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3354,25 +4071,35 @@ msgid "" "be of interest to programmers using the package. These files are called " "\"package data\"." msgstr "" +"Часто в :term:`пакет ` необходимо установить дополнительные " +"файлы. Эти файлы часто представляют собой данные, тесно связанные с " +"реализацией пакета, или текстовые файлы, содержащие документацию, которая " +"может быть интересна программистам, использующим пакет. Такие файлы " +"называются \"данными пакета\"." -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" +"Значение должно представлять собой отображение имени пакета на список " +"относительных имен путей, которые должны быть скопированы в пакет. Пути " +"интерпретируются как относительные к директории, содержащей пакет." -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" +"Дополнительную информацию см. в :std:doc:`Including Data Files ` из :std:doc:`setuptools docs `." -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "``data_files``" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3380,8 +4107,14 @@ msgid "" "that. It is mostly useful if you need to install files which are used by " "other programs, which may be unaware of Python packages." msgstr "" +"Хотя конфигурирования :ref:`Package Data` достаточно для большинства " +"потребностей, в некоторых случаях вам может понадобиться разместить файлы " +"данных *вне* вашего :term:`packages `. Директива " +"``data_files`` позволяет это сделать. В основном она полезна, если вам нужно " +"установить файлы, используемые другими программами, которые могут не знать о " +"пакетах Python." -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3392,86 +4125,63 @@ msgid "" "``files`` is interpreted relative to the :file:`setup.py` script at the top " "of the project source distribution." msgstr "" +"Каждая пара ``(директория, файлы)`` в последовательности указывает " +"директорию установки и файлы для установки. Каталог ``directory`` должен " +"быть относительным путем (хотя это может измениться в будущем, см. `wheel " +"Issue #92 `_), и он " +"интерпретируется относительно префикса установки (Python'овский ``sys." +"prefix`` для установки по умолчанию; ``site.USER_BASE`` для установки " +"пользователем). Каждое имя файла в ``files`` интерпретируется относительно " +"скрипта :file:`setup.py`` в верхней части исходного дистрибутива проекта." -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" +"Дополнительную информацию можно найти в разделе distutils на :ref:`Установка " +"дополнительных файлов `." -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " "Alternatively, if you must use ``python setup.py``, then you need to pass " "the ``--old-and-unmanageable`` option." msgstr "" +"При установке пакетов как яиц, ``data_files`` не поддерживается. Поэтому, " +"если ваш проект использует :ref:`setuptools`, то для его установки " +"необходимо использовать ``pip``. В противном случае, если вы должны " +"использовать ``python setup.py``, то вам нужно передать опцию ``-old-and-" +"unmanageable``." -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 #, fuzzy msgid "``scripts``" msgstr "scripts" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " "the recommended approach to achieve cross-platform compatibility is to use :" "ref:`console_scripts` entry points (see below)." msgstr "" +"Хотя ``setup()`` поддерживает ключевое слово :ref:`scripts ` для указания на готовые скрипты для " +"установки, рекомендуемый подход для достижения кроссплатформенной " +"совместимости - использовать точки входа :ref:`console_scripts` (см. ниже)." -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" -msgstr "``entry_points``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:517 -msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -#, fuzzy -msgid "``console_scripts``" -msgstr "console_scripts" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 +#: ../source/guides/distributing-packages-using-setuptools.rst:295 msgid "Choosing a versioning scheme" msgstr "Выбор схемы управления версиями" -#: ../source/guides/distributing-packages-using-setuptools.rst:552 +#: ../source/guides/distributing-packages-using-setuptools.rst:298 msgid "Standards compliance for interoperability" msgstr "Соответствие стандартам совместимости" -#: ../source/guides/distributing-packages-using-setuptools.rst:554 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" "Different Python projects may use different versioning schemes based on the " "needs of that particular project, but all of them are required to comply " @@ -3479,159 +4189,207 @@ msgid "" "identifiers>` specified in :pep:`440` in order to be supported in tools and " "libraries like ``pip`` and ``setuptools``." msgstr "" +"Разные проекты Python могут использовать различные схемы версионирования в " +"зависимости от потребностей конкретного проекта, но все они должны " +"соответствовать гибкой схеме :pep:`public version scheme <440#public-version-" +"identifiers>`, указанной в :pep:`440`, чтобы поддерживаться в таких " +"инструментах и библиотеках, как ``pip`` и ``setuptools``." -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "Вот несколько примеров совместимых номеров версий::" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" "`version normalisation <440#normalization>` that maps variant spellings of " "different version numbers to a standardised canonical form." msgstr "" +"Для дальнейшего учета исторических вариаций в подходах к нумерации версий, :" +"pep:`440` также определяет комплексную технику нормализации :pep:`версий " +"<440#normalization>`, которая отображает варианты написания различных " +"номеров версий в стандартизированную каноническую форму." -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "Выбор схемы" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "Семантическое версионирование (предпочитаемый вариант)" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" +"Для новых проектов рекомендуемая схема версионирования основана на `Semantic " +"Versioning `_, но использует другой подход к работе с " +"пре-релизами и метаданными сборки." -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" +"Суть семантического версионирования заключается в трехчастной схеме " +"нумерации MAJOR.MINOR.MAINTENANCE, в которой автор проекта увеличивает " +"количество версий:" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," -msgstr "" +msgstr "MAJOR версии, когда они вносят несовместимые изменения в API," -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" +"MINOR-версии, когда они добавляют функциональность, совместимую с обратной " +"версией, и" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." -msgstr "" +msgstr "MAINTENANCE при исправлении ошибок, совместимых с обратной версией." -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " "~= X.Y`` requires at least release X.Y, but also allows any later release " "with a matching MAJOR version." msgstr "" +"Принятие такого подхода автором проекта позволяет пользователям использовать " +"спецификаторы :pep:`\"compatible release\" <440#compatible-release>`, где " +"``name ~= X.Y`` требует как минимум релиза X.Y, но также позволяет " +"использовать любой более поздний релиз с соответствующей MAJOR-версией." -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" +"Python-проекты, использующие семантическое версионирование, должны следовать " +"пунктам 1-8 спецификации `Semantic Versioning 2.0.0` `_." -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "Версионирование на основе дат" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" +"Семантическое версионирование подходит не для всех проектов, например, для " +"тех, которые имеют регулярную периодичность выпуска релизов и процесс " +"обесценивания, предусматривающий предупреждения за несколько релизов до " +"удаления функции." -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" +"Ключевое преимущество версионности на основе даты заключается в том, что по " +"номеру версии можно легко определить, насколько устарел базовый набор " +"функций конкретного выпуска." -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" +"Номера версий для проектов, основанных на дате, обычно имеют вид YEAR.MONTH " +"(например, ``12.04``, ``15.10``)." -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "Последовательное версионирование" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" +"Это простейшая схема версионирования, состоящая из одного числа, которое " +"увеличивается при каждом выпуске." -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" +"Хотя серийным версионированием очень легко управлять как разработчику, его " +"сложнее всего отслеживать как конечному пользователю, поскольку серийные " +"номера версий передают мало или вообще не передают информации об обратной " +"совместимости API." -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "Гибридные схемы" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " "numbering scheme that readily conveys the approximate age of a release, but " "doesn't otherwise commit to a particular release cadence within the year." msgstr "" +"Возможны комбинации вышеперечисленных схем. Например, проект может сочетать " +"версионирование по дате с серийным версионированием, чтобы создать схему " +"нумерации YEAR.SERIAL, которая легко передает приблизительный возраст " +"релиза, но в остальном не обязывает к определенной периодичности выпуска в " +"течение года." -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "Версионирование предварительных выпусков" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" +"Независимо от базовой схемы версий, предварительные выпуски для данного " +"финального выпуска могут быть опубликованы как:" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" -msgstr "" +msgstr "ноль или более выпусков dev (обозначаются суффиксом \".devN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" -msgstr "" +msgstr "ноль или более альфа-релизов (обозначаются суффиксом \".aN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" -msgstr "" +msgstr "ноль или более бета-версий (обозначаются суффиксом \".bN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" -msgstr "" +msgstr "ноль или более кандидатов на выпуск (обозначаются суффиксом \".rcN\")" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" +"``pip`` и другие современные программы установки пакетов Python по умолчанию " +"игнорируют предварительные выпуски, когда решают, какие версии зависимостей " +"устанавливать." -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "Идентификаторы локальных версий" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3640,18 +4398,27 @@ msgid "" "builds not intended for publication, or modified variants of a release " "maintained by a redistributor." msgstr "" +"Идентификаторы публичных версий предназначены для поддержки распространения " +"через :term:`PyPI `. Средства распространения " +"программного обеспечения Python также поддерживают понятие :pep:`локального " +"идентификатора версии <440#local-version-identifiers>`, который может " +"использоваться для идентификации локальных сборок разработки, не " +"предназначенных для публикации, или модифицированных вариантов релиза, " +"поддерживаемого редистрибьютором." -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" +"Идентификатор локальной версии имеет вид ``<идентификатор публичной " +"версии>+<метка локальной версии>``. Например::" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "Работа в «режиме разработки»" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3659,14 +4426,21 @@ msgid "" "as editable will be reflected the next time an interpreter process is " "started." msgstr "" +"Вы можете установить проект в режиме \"редактируемый\" или " +"\"разрабатываемый\", пока вы работаете над ним. Если проект установлен как " +"редактируемый, его можно редактировать на месте без переустановки: изменения " +"исходных файлов Python в проектах, установленных как редактируемые, будут " +"отражены при следующем запуске процесса интерпретатора." -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" +"Чтобы установить пакет Python в режиме \"редактируемый\"/\"разработка\", " +"измените каталог на корень каталога проекта и выполните команду:" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3675,30 +4449,47 @@ msgid "" "declared with ``console_scripts``. Dependencies will be installed in the " "usual, non-editable mode." msgstr "" +"Флаг командной строки pip ``-e`` - это сокращение от ``-editable``, а ``.`` " +"означает текущий рабочий каталог, так что вместе это означает установку " +"текущего каталога (т.е. вашего проекта) в режиме редактирования. При этом " +"также будут установлены все зависимости, объявленные с помощью " +"``install_requires``, и все скрипты, объявленные с помощью " +"``console_scripts``. Зависимости будут установлены в обычном, " +"нередактируемом режиме." -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " "want \"bar\" installed from VCS in editable mode, then you could construct a " "requirements file like so::" msgstr "" +"Возможно, вы захотите установить некоторые из ваших зависимостей в " +"редактируемом режиме. Например, предположим, что ваш проект требует \"foo\" " +"и \"bar\", но вы хотите, чтобы \"bar\" устанавливался из VCS в редактируемом " +"режиме, тогда вы можете создать файл требований следующим образом::" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" +"В первой строке говорится об установке вашего проекта и всех зависимостей. " +"Вторая строка переопределяет зависимость \"bar\" так, чтобы она выполнялась " +"из VCS, а не из PyPI." -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" +"Если же вы хотите установить \"Бар\" из локальной директории в редактируемом " +"режиме, файл требований должен выглядеть следующим образом, с локальными " +"путями в верхней части файла::" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3706,47 +4497,62 @@ msgid "" "the pip docs. For more on VCS installs, see the :ref:`VCS Support ` section of the pip docs." msgstr "" +"В противном случае зависимость будет выполняться из PyPI, что обусловлено " +"порядком установки файла требований. Подробнее о файлах требований смотрите " +"раздел :ref:`Requirements File ` в документации " +"pip. Подробнее о VCS-установках смотрите в разделе :ref:`VCS Support ` документации pip." -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" +"Наконец, если вы не хотите устанавливать никаких зависимостей, вы можете " +"выполнить команду:" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" +"Для получения дополнительной информации см. раздел :doc:`Режим разработки " +"` в :ref:`setuptools` docs." -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "Упаковка вашего проекта" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" "`Distribution ` (aka \":term:`Package `\") for your project." msgstr "" +"Чтобы ваш проект можно было установить из индекса :term:`Package Index`, " +"например :term:`PyPI `, вам нужно будет " +"создать :term:`Distribution ` (он же \":term:`Package " +"`\") для вашего проекта." -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" +"Прежде чем вы сможете построить колеса и диски для своего проекта, вам нужно " +"будет установить пакет ``build``:" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "Распространение в исходных кодах" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3755,11 +4561,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "Колёса" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3767,95 +4573,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "Колёса чистого Python'а" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "Для построения колеса выполните:" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "Платформо-зависимые колёса" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "Загрузка вашего проекта на PyPI" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3863,7 +4669,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3871,7 +4677,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3880,7 +4686,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3890,78 +4696,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Создание учётной записи" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "Загрузите свои дистрибутивы" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3969,7 +4775,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3977,14 +4783,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "Удаление поддержки старых версий Python'а" @@ -4088,10 +4886,8 @@ msgid "Steps:" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:74 -#, fuzzy -#| msgid "`setuptools` version should be above 24.0.0." msgid "``setuptools`` version should be above 24.0.0." -msgstr "Версия `setuptools` должна быть выше 24.0.0." +msgstr "``setuptools`` версия должна быть выше 24.0.0." #: ../source/guides/dropping-older-python-versions.rst:77 msgid "2. Specify the version ranges for supported Python distributions" @@ -4104,96 +4900,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "Примеры::" +msgid "Examples:" +msgstr "Примеры:" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "3. Перед публикацией проверьте метаданные" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "4. Используйте Twine для публикации" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "Удаление выпуска Python'а" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4208,9 +4995,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4492,7 +5279,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "Spack" @@ -4597,6 +5384,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "Например:" @@ -4625,7 +5413,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4787,10 +5575,8 @@ msgid "" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 -#, fuzzy -#| msgid "Installing virtualenv" msgid "Install packages in a virtual environment using pip and venv" -msgstr "Установка virtualenv" +msgstr "Установка пакетов в виртуальной среде с использованием pip и venv" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 msgid "" @@ -4801,12 +5587,11 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 #, fuzzy -#| msgid "Creating Virtual Environments" msgid "Create and activate a virtual environment" msgstr "Создание виртуальных окружений" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4816,7 +5601,6 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 #, fuzzy -#| msgid "Using requirements files" msgid "Use and create a requirements file" msgstr "Использование файлов требований" @@ -4843,13 +5627,11 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 #, fuzzy -#| msgid "Creating Virtual Environments" msgid "Create and Use Virtual Environments" msgstr "Создание виртуальных окружений" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 #, fuzzy -#| msgid "Creating Virtual Environments" msgid "Create a new virtual environment" msgstr "Создание виртуальных окружений" @@ -4871,34 +5653,34 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 #, fuzzy msgid "Activate a virtual environment" msgstr "Создание виртуальных окружений" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4906,82 +5688,77 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 #, fuzzy -#| msgid "Creating Virtual Environments" msgid "Deactivate a virtual environment" msgstr "Создание виртуальных окружений" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 #, fuzzy -#| msgid "Creating Virtual Environments" msgid "Reactivate a virtual environment" msgstr "Создание виртуальных окружений" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 -#, fuzzy -#| msgid "" -#| "The Python installers for Windows include pip. You can make sure that pip " -#| "is up-to-date by running:" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -"Установщики Python для Windows включают pip. Вы можете убедиться, что pip " -"обновлён до последней версии, запустив:" +"Python установщики для macOS включают pip. На Linux вам, возможно, придется " +"установить дополнительный пакет, такой как ``python3-pip``. Вы можете " +"убедиться, что pip обновляется при запуске:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" @@ -4989,84 +5766,79 @@ msgstr "" "Установщики Python для Windows включают pip. Вы можете убедиться, что pip " "обновлён до последней версии, запустив:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 -#, fuzzy -#| msgid "Installing virtualenv" +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" -msgstr "Установка virtualenv" +msgstr "Установка пакетов с помощью pip" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy -#| msgid "Installing packages" msgid "Install a package" msgstr "Установка пакетов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy -#| msgid "Installing specific versions" msgid "Install a specific package version" msgstr "Установка определённых версий" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy msgid "Install extras" msgstr "Установка пакетов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy -#| msgid "Installing from source" msgid "Install a package from source" msgstr "Установка из исходных кодов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5074,114 +5846,110 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 #, fuzzy -#| msgid "Installing from version control systems" msgid "Install from version control systems" msgstr "Установка из систем управления версиями" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 #, fuzzy -#| msgid "Installing from local archives" msgid "Install from local archives" msgstr "Установка из локальных архивов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy -#| msgid "Installing from other Indexes" msgid "Install from other package indexes" msgstr "Установка из других индексов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "Обновление пакетов" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy -#| msgid "Using requirements files" msgid "Using a requirements file" msgstr "Использование файлов требований" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "Заморозка зависимостей" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5190,7 +5958,6 @@ msgstr "" #: ../source/guides/installing-using-virtualenv.rst:2 #, fuzzy -#| msgid "Installing virtualenv" msgid "Installing packages using virtualenv" msgstr "Установка virtualenv" @@ -5595,7 +6362,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:36 #, fuzzy msgid "``python -m build``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``python -m build``" #: ../source/guides/modernize-setup-py-project.rst:42 #: ../source/guides/modernize-setup-py-project.rst:66 @@ -5611,9 +6378,8 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:48 #, fuzzy -#| msgid "Get started" msgid "Where to start?" -msgstr "Начало работы" +msgstr "С чего начать?" #: ../source/guides/modernize-setup-py-project.rst:50 msgid "" @@ -5636,21 +6402,17 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:68 #, fuzzy -#| msgid "Linux distribution packages" msgid ":ref:`distributing-packages`" -msgstr "Распространяемые пакеты Linux" +msgstr ":ref:`distributing-packages`" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -#, fuzzy -#| msgid "Declaring build system dependencies" -msgid ":ref:`declaring-build-dependencies`" -msgstr "Объявление зависимостей системы сборки" +msgid ":ref:`pyproject-build-system-table`" +msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5699,18 +6461,16 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:126 #, fuzzy msgid "``python -m build --no-isolation``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``python -m build --no-isolation``" #: ../source/guides/modernize-setup-py-project.rst:127 #, fuzzy msgid "``python -m install --no-build-isolation``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgstr "``python -m install --no-build-isolation``" #: ../source/guides/modernize-setup-py-project.rst:135 -#, fuzzy -#| msgid "Using package metadata" msgid "How to handle packaging metadata?" -msgstr "Использование метаданных пакета" +msgstr "Как обрабатывать метаданные упаковки?" #: ../source/guides/modernize-setup-py-project.rst:137 msgid "" @@ -5724,7 +6484,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5763,11 +6523,12 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +msgid ":ref:`pyproject-toml-spec`" +msgstr "Спецификация точек входа" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6150,7 +6911,6 @@ msgstr "" #: ../source/guides/packaging-binary-extensions.rst:236 #, fuzzy -#| msgid "Extension Module" msgid "Extension module lifecycle" msgstr "Модуль расширения" @@ -6386,11 +7146,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "Упаковка пакетов пространства имён" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6399,19 +7159,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6422,17 +7182,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "Создание пакета пространства имён" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6440,17 +7200,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "Родные пакеты пространства имён" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6458,7 +7218,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6466,7 +7226,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6475,27 +7235,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6503,13 +7263,12 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 #, fuzzy -#| msgid "Using namespace packages" msgid "Legacy namespace packages" msgstr "Использование пакетов пространства имён" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6517,13 +7276,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6531,11 +7290,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "Пакеты пространства имён в стиле pkgutil" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6544,21 +7303,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6566,17 +7325,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "Пакеты пространства имён в стиле pkg_resources" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6588,19 +7347,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6609,13 +7368,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6810,10 +7569,8 @@ msgid "" msgstr "" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:161 -#, fuzzy -#| msgid "Linux distribution packages" msgid "Signing the distribution packages" -msgstr "Распространяемые пакеты Linux" +msgstr "Подписание пакетов распространения" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:163 msgid "" @@ -6905,7 +7662,6 @@ msgstr "" #: ../source/guides/section-install.rst:3 #, fuzzy -#| msgid "Installation format" msgid "Installation" msgstr "Формат установки" @@ -6913,44 +7669,52 @@ msgstr "Формат установки" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6958,39 +7722,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6999,52 +7763,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7797,13 +8561,12 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 #, fuzzy -#| msgid "Configuring your project" msgid "Writing your ``pyproject.toml``" msgstr "Настройка вашего проекта" @@ -7864,7 +8627,6 @@ msgstr "" #: ../source/guides/writing-pyproject-toml.rst:45 #, fuzzy -#| msgid "Declaring build system dependencies" msgid "Declaring the build backend" msgstr "Объявление зависимостей системы сборки" @@ -7919,95 +8681,128 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 -#, fuzzy -#| msgid "Configuring your project" +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." -msgstr "Настройка вашего проекта" +msgstr "Положите версию вашего проекта." -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy -#| msgid "Using requirements files" msgid "Dependencies and requirements" msgstr "Использование файлов требований" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 #, fuzzy -#| msgid "Creating the package files" msgid "Creating executable scripts" msgstr "Создание файлов пакета" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -8015,133 +8810,181 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 #, fuzzy -#| msgid "Configuring your project" msgid "About your project" msgstr "Настройка вашего проекта" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." -msgstr "" +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → ``reStructuredText `_ (без расширений Sphinx)." -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 -#, fuzzy -#| msgid "For example:" +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" -msgstr "Например:" +msgstr "Полный пример" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8178,7 +9021,6 @@ msgstr "" #: ../source/index.rst:36 #, fuzzy -#| msgid "Overview" msgid "Overview and Flow" msgstr "Обзор" @@ -8254,9 +9096,8 @@ msgstr "" #: ../source/index.rst:85 #, fuzzy -#| msgid "Deploying Python applications" msgid ":doc:`discussions/deploying-python-applications`" -msgstr "Развёртывание приложений на Python'е" +msgstr ":doc:`discussions/deploying-python-applications`" #: ../source/index.rst:86 msgid ":doc:`discussions/pip-vs-easy-install`" @@ -8580,9 +9421,11 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" #: ../source/key_projects.rst:240 msgid "" @@ -8592,10 +9435,12 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" +":doc:`Документы <индекс>` | `Вопросы `__ | `GitHub `__" #: ../source/key_projects.rst:251 msgid "This guide!" @@ -8621,10 +9466,8 @@ msgid "" msgstr "" #: ../source/key_projects.rst:272 -#, fuzzy -#| msgid "setuptools" msgid "Setuptools" -msgstr "setuptools" +msgstr "Инструменты настройки" #: ../source/key_projects.rst:274 msgid "" @@ -8655,13 +9498,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8674,18 +9516,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "twine" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8694,21 +9536,21 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "virtualenv" -#: ../source/key_projects.rst:332 -#, fuzzy +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -"`Документация `__ | " -"`Замечания `__" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8719,42 +9561,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "Warehouse" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "wheel" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8763,22 +9605,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "Проекты, не связанные с PyPA" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "buildout" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8786,15 +9628,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "conda" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8803,14 +9645,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8823,17 +9665,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "devpi" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8841,17 +9683,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "enscons" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8863,17 +9705,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "Hashdist" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8884,41 +9726,41 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 #, fuzzy msgid "" "`Docs `__ | `GitHub `__" msgstr "" -"`Документация `__ | " -"`Замечания `__" +"`Docs `__ | `GitHub `__" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 #, fuzzy msgid "meson-python" msgstr "python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 #, fuzzy msgid "" "`Docs `__ | `GitHub `__" msgstr "" -"`Документация `__ | " -"`Замечания `__" +"`Docs `__ | `GitHub `__" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8926,46 +9768,45 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy -#| msgid "`Source `__" msgid "`GitHub `__" -msgstr "`Исходный код `__" +msgstr "`GitHub `__" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8974,18 +9815,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8996,17 +9837,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -9014,17 +9855,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -9034,17 +9875,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -9054,17 +9895,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9074,18 +9915,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "scikit-build" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9096,23 +9937,23 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 #, fuzzy -#| msgid "scikit-build" msgid "scikit-build-core" msgstr "scikit-build" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 #, fuzzy msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -"`Документация `__ | " -"`Замечания `__" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9140,7 +9981,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9159,24 +10000,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "zest.releaser" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9184,15 +10025,15 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "Проекты в стандартное библиотеке" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "ensurepip" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 #, fuzzy msgid "" "`Docs `__ | `Issues " @@ -9201,7 +10042,7 @@ msgstr "" "`Документация `__ | " "`Замечания `__" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9209,20 +10050,19 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "venv" -#: ../source/key_projects.rst:731 -#, fuzzy +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -"`Документация `__ | " -"`Замечания `__" +"`Docs `__ | `Issues `__" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -9858,7 +10698,6 @@ msgstr "Добавлен :pep:`518` (:pr:`281`)." #: ../source/overview.rst:3 #, fuzzy -#| msgid "An Overview of Packaging for Python" msgid "Overview of Python Packaging" msgstr "Обзор создания Python'ьих пакетов" @@ -10268,9 +11107,8 @@ msgstr "" "управлять зависимостями, требует Python 3.5+)" #: ../source/overview.rst:250 -#, fuzzy msgid ":gh:`shiv ` (requires Python 3)" -msgstr "`shiv `_ (требует Python 3)" +msgstr ":gh:`shiv ` (требуется Python 3)" #: ../source/overview.rst:252 msgid "" @@ -10615,25 +11453,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "Формат распространения двоичных пакетов" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10644,86 +11474,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "Обоснование" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "Подробности" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10732,35 +11529,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10768,32 +11565,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10801,41 +11598,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "Формат файла" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10844,14 +11641,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10859,7 +11656,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10867,33 +11664,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10901,25 +11698,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10930,63 +11727,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10994,71 +11791,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -11066,28 +11863,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11096,22 +11893,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11119,29 +11916,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11151,7 +11948,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11159,25 +11956,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11185,85 +11982,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "ЧаВо" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11273,11 +12024,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11286,38 +12037,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11325,7 +12076,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11333,18 +12084,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11353,7 +12104,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11364,7 +12115,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11382,7 +12133,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11391,70 +12142,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" -msgstr "Изменения" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." +msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "Авторские права" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "Спецификации основных метаданных" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "Все остальные поля являются необязательными." -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "Имя" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11556,41 +12304,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "Версия" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11598,20 +12346,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11619,27 +12367,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "Platform (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "Примеры::" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "Supported-Platform (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11647,19 +12407,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "Сводка" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "Однострочная сводка того, что делает дистрибутив." -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11667,7 +12427,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11675,7 +12435,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11683,31 +12443,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "Description-Content-Type" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "Keywords" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11821,91 +12581,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "Home-page" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "Download-URL" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "Автор" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "Author-email" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Сопровождающий" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "Maintainer-email" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "Лицензия" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11915,11 +12675,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "Classifier (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11927,43 +12687,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "Requires-Dist (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11971,64 +12731,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "Requires-Python" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "Requires-External (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -12036,13 +12796,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -12050,36 +12810,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "Project-URL (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "Provides-Extra (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12088,13 +12848,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12102,20 +12862,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12123,7 +12883,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12133,11 +12893,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "Редко используемые поля" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12145,7 +12905,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12155,18 +12915,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "Provides-Dist (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12175,7 +12935,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12186,67 +12946,65 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "Obsoletes-Dist (можно использовать несколько раз)" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 #, fuzzy -#| msgid "Rarely Used Fields" msgid "Deprecated Fields" msgstr "Редко используемые поля" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 #, fuzzy -#| msgid "Requirements" msgid "Requires" msgstr "Требования" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12257,33 +13015,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12292,3400 +13050,3386 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 #, fuzzy msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "Разметка reStructuredText: http://docutils.sourceforge.net/" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" -msgstr "Объявление зависимостей системы сборки" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "Спецификаторы зависимостей" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Спецификация" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Спецификация" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -#, fuzzy -msgid "``authors``" -msgstr "Автор" - -#: ../source/specifications/declaring-project-metadata.rst:55 -#, fuzzy -msgid "``dependencies``" -msgstr "Заморозка зависимостей" - -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -#, fuzzy -msgid "``entry-points``" -msgstr "``entry_points``" - -#: ../source/specifications/declaring-project-metadata.rst:59 -#, fuzzy -msgid "``gui-scripts``" -msgstr "scripts" - -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "Сопровождающий" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 +#: ../source/specifications/dependency-specifiers.rst:132 #, fuzzy -msgid "``optional-dependencies``" -msgstr "Внешние зависимости" - -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "" +msgid "Names" +msgstr "Имя" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Версия" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:176 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Версия Python’а" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:236 +#, fuzzy +msgid "``os_name``" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:237 +#, fuzzy +msgid "``os.name``" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:238 +#, fuzzy +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "python_requires" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:262 +#, fuzzy +msgid "``3.4``, ``2.7``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "python_requires" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +#, fuzzy +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:268 +#, fuzzy +msgid "``cpython``" +msgstr "python" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:275 +#, fuzzy +msgid "``test``" +msgstr "``text/x-rst``" + +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 -msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" -msgstr "Спецификаторы зависимостей" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:8 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:17 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url.rst:51 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "Используйте ``pip`` для установки Pipenv:" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -#, fuzzy -msgid "Names" -msgstr "Имя" - -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "Версия" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 -msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Версия Python’а" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -#, fuzzy -msgid "``os_name``" -msgstr "``name``" - -#: ../source/specifications/dependency-specifiers.rst:235 -#, fuzzy -msgid "``os.name``" -msgstr "``name``" - -#: ../source/specifications/dependency-specifiers.rst:236 -#, fuzzy -msgid "``posix``, ``java``" -msgstr "``pipenv``, ``nose``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:102 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:114 +#, fuzzy +msgid "Projects in subdirectories" +msgstr "Обзор проектов" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" +msgstr "Git" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" +msgstr "Домашняя страница" + +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "python_requires" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" +msgstr "Mercurial" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:260 -#, fuzzy -msgid "``3.4``, ``2.7``" -msgstr "``0.1.6``, ``1.4.2``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "hg" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "python_requires" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:181 #, fuzzy -msgid "``3.4.0``, ``3.5.0b1``" -msgstr "``0.1.6``, ``1.4.2``" +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" +msgstr "bzr" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -#, fuzzy -msgid "``cpython``" -msgstr "python" - -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"An error except when defined by the context interpreting the specification." +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -#, fuzzy -msgid "``test``" -msgstr "``text/x-rst``" - -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "Спецификация точек входа" + +#: ../source/specifications/entry-points.rst:7 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:11 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:19 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Модель данных" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -#, fuzzy -msgid "``pip install app``" -msgstr "Используйте ``pip`` для установки Pipenv:" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +msgid "distro" +msgstr "distlib" + +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "packaging" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python-специфический менеджер пакетов" + +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "Кроссплатформенный менеджер пакетов conda" + +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:170 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -#, fuzzy -msgid "Projects in subdirectories" -msgstr "Обзор проектов" - -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:173 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:177 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" -msgstr "Git" - -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" -msgstr "Домашняя страница" - -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" -msgstr "https://git-scm.com/" - -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:255 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" -msgstr "Mercurial" - -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" -msgstr "hg" - -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" -msgstr "Bazaar" - -#: ../source/specifications/direct-url-data-structure.rst:189 -#, fuzzy -#| msgid "https://www.mercurial-scm.org/" -msgid "https://www.breezy-vcs.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" -msgstr "bzr" - -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" -msgstr "svn" +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Создание виртуальных окружений" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" -msgstr "Спецификация точек входа" - -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." -msgstr "" - -#: ../source/specifications/entry-points.rst:14 -msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." -msgstr "" - -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "Модель данных" - -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "Типы документации" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." -msgstr "" - -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "``pip install``" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "Например::" +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "``pip install --user``" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Авторские права" + +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 -msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/index.rst:6 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 -msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -#, fuzzy -#| msgid "distlib" -msgid "distro" -msgstr "distlib" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "packaging" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 +#: ../source/specifications/inline-script-metadata.rst:79 #, fuzzy -#| msgid "The conda cross-platform package manager" -msgid "Python-specific package manager" -msgstr "Кроссплатформенный менеджер пакетов conda" +msgid "pyproject type" +msgstr "Индекс по проектам" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 -msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -#, fuzzy -#| msgid "The conda cross-platform package manager" -msgid "distro package manager" -msgstr "Кроссплатформенный менеджер пакетов conda" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:98 +msgid "" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:108 +#, fuzzy +msgid "Example" +msgstr "Примеры" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 -msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +msgid "Reference Implementation" +msgstr "Типы документации" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +msgid "Recommendations" +msgstr "Рекомендации по инструментам" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:5 +#, fuzzy +msgid "Package name normalization" +msgstr "Версия пакета" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "Переводы" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -msgid "Guide users towards virtual environments" -msgstr "Создание виртуальных окружений" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:25 +#, fuzzy +msgid "python tag" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 +#: ../source/specifications/platform-compatibility-tags.rst:49 #, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Типы документации" +msgid "Python Tag" +msgstr "Python Tag" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 -msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 +#: ../source/specifications/platform-compatibility-tags.rst:55 #, fuzzy -msgid "``pip install``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgid "cp: CPython" +msgstr "cp: CPython" -#: ../source/specifications/externally-managed-environments.rst:420 -msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" +msgstr "ip: IronPython" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 +#: ../source/specifications/platform-compatibility-tags.rst:58 #, fuzzy -msgid "``pip install --prefix=/some/path``" -msgstr "Используйте ``pip`` для установки Pipenv:" +msgid "jy: Jython" +msgstr "python" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -msgid "``pip install --user``" -msgstr "Используйте ``pip`` для установки Pipenv:" +#: ../source/specifications/platform-compatibility-tags.rst:62 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:93 +#, fuzzy +msgid "Platform Tag" +msgstr "Платформо-зависимые колёса" + +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:107 +#, fuzzy +msgid "``manylinux``" +msgstr "Сопровождающий" + +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:114 +msgid "" +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:137 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:143 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" +msgstr "Инструмент" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "per project index" -msgid "pyproject type" -msgstr "Индекс по проектам" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -#, fuzzy -msgid "Example" -msgstr "Примеры" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Типы документации" - -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Tool recommendations" -msgid "Recommendations" -msgstr "Рекомендации по инструментам" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -#, fuzzy -msgid "Package name normalization" -msgstr "Версия пакета" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "Переводы" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:261 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:264 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -#, fuzzy -msgid "python tag" -msgstr "python" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:300 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -#, fuzzy -msgid "Python Tag" -msgstr "Python 2::" - -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -#, fuzzy -msgid "cp: CPython" -msgstr "python" - -#: ../source/specifications/platform-compatibility-tags.rst:56 -#, fuzzy -msgid "ip: IronPython" -msgstr "python" - -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -#, fuzzy -msgid "jy: Jython" -msgstr "python" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:93 -#, fuzzy -msgid "Platform Tag" -msgstr "Платформо-зависимые колёса" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:96 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 +#: ../source/specifications/pyproject-toml.rst:6 #, fuzzy -msgid "``manylinux``" -msgstr "Сопровождающий" +msgid "``pyproject.toml`` specification" +msgstr "Спецификация точек входа" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:29 +#, fuzzy +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "Объявление зависимостей системы сборки" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "Инструмент" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:132 +#, fuzzy +msgid "``authors``" +msgstr "Автор" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:134 +#, fuzzy +msgid "``dependencies``" +msgstr "Заморозка зависимостей" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:137 +#, fuzzy +msgid "``entry-points``" +msgstr "``entry_points``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:138 +#, fuzzy +msgid "``gui-scripts``" +msgstr "scripts" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "Сопровождающий" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:143 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "Внешние зависимости" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:346 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:359 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:32 -msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:398 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:411 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:427 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15693,7 +16437,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15702,11 +16446,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15717,21 +16461,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15743,7 +16487,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15754,7 +16498,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15766,41 +16510,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15808,7 +16552,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15816,58 +16560,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15875,7 +16619,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15883,13 +16627,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15898,7 +16642,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15907,18 +16651,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15926,7 +16670,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15936,11 +16680,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15948,15 +16692,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15964,11 +16708,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15976,29 +16720,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -16007,11 +16751,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -16019,14 +16763,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -16035,7 +16779,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16052,7 +16796,6 @@ msgstr "" #: ../source/specifications/section-installation-metadata.rst:3 #, fuzzy -#| msgid "Installation format" msgid "Package Installation Metadata" msgstr "Формат установки" @@ -16172,10 +16915,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16194,7 +16937,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:76 #, fuzzy -#| msgid "Source distribution format" msgid "Source distribution archive features" msgstr "Формат распространения в исходных кодах" @@ -16347,24 +17089,23 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "Спецификаторы версии" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy -#| msgid "Specifications" msgid "Definitions" msgstr "Спецификации" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16372,7 +17113,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16380,19 +17121,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16400,25 +17141,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Версия" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16426,28 +17167,27 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy -#| msgid "Local version identifiers" msgid "Public version identifiers" msgstr "Идентификаторы локальных версий" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16455,7 +17195,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16463,63 +17203,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16527,11 +17267,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16540,7 +17280,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16550,7 +17290,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16559,7 +17299,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16567,23 +17307,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16597,7 +17337,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16605,7 +17345,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16617,38 +17357,37 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 #, fuzzy -#| msgid "Publishing releases" msgid "Final releases" msgstr "Публикация выпусков" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16656,21 +17395,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "Например::" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16678,37 +17421,36 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-releases" msgstr "Версионирование предварительных выпусков" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16716,50 +17458,49 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy -#| msgid "zest.releaser" msgid "Post-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16767,7 +17508,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16775,11 +17516,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16787,11 +17528,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16799,20 +17540,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16821,13 +17562,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16837,29 +17578,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Версия" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16870,14 +17611,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16885,23 +17626,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Переводы" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16910,13 +17651,12 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release separators" msgstr "Версионирование предварительных выпусков" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16926,13 +17666,12 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 #, fuzzy -#| msgid "Pre-release versioning" msgid "Pre-release spelling" msgstr "Версионирование предварительных выпусков" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16942,11 +17681,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16954,11 +17693,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16969,13 +17708,12 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 #, fuzzy -#| msgid "Pre-release versioning" msgid "Post release spelling" msgstr "Версионирование предварительных выпусков" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16983,11 +17721,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16995,11 +17733,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -17009,11 +17747,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -17021,11 +17759,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -17033,13 +17771,12 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 #, fuzzy -#| msgid "Local version identifiers" msgid "Local version segments" msgstr "Идентификаторы локальных версий" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -17047,11 +17784,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -17060,11 +17797,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -17073,13 +17810,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 -#, fuzzy -#| msgid "Here are some examples of compliant version numbers::" +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" -msgstr "Вот несколько примеров совместимых номеров версий::" +msgstr "Примеры совместимых схем версий" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -17089,7 +17824,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -17097,71 +17832,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 -#, fuzzy -#| msgid "Serial versioning" +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" -msgstr "Последовательное версионирование" +msgstr "Простая версификация \"major.minor\" ::" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17169,48 +17902,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17221,7 +17954,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17231,17 +17964,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17250,20 +17983,19 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 #, fuzzy -#| msgid "Serial versioning" msgid "Semantic versioning" msgstr "Последовательное версионирование" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17274,7 +18006,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17282,32 +18014,31 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 #, fuzzy -#| msgid "Date based versioning" msgid "DVCS based version labels" msgstr "Версионирование на основе дат" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17315,32 +18046,31 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 #, fuzzy -#| msgid "Date based versioning" msgid "Olson database versioning" msgstr "Версионирование на основе дат" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17348,60 +18078,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17410,81 +18140,80 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy -#| msgid "Version" msgid "Version matching" msgstr "Версия" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17493,7 +18222,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17501,31 +18230,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17533,7 +18262,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17542,7 +18271,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17552,14 +18281,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17568,29 +18297,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "Версия" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17599,27 +18328,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17629,7 +18358,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17639,13 +18368,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17866,7 +18594,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17874,7 +18602,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17885,17 +18613,16 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy -#| msgid "For example::" msgid "Remote URL examples::" msgstr "Например::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17903,7 +18630,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17911,7 +18638,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17923,43 +18650,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17968,20 +18695,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -17989,9 +18716,8 @@ msgid "" msgstr "" #: ../source/specifications/virtual-environments.rst:6 -#, fuzzy msgid "Python Virtual Environments" -msgstr "Создание виртуальных окружений" +msgstr "Виртуальные среды Python" #: ../source/specifications/virtual-environments.rst:8 msgid "" @@ -18669,6 +19395,7 @@ msgid "" msgstr "" #: ../source/tutorials/managing-dependencies.rst:35 +#, fuzzy msgid "Use ``pip`` to install Pipenv:" msgstr "Используйте ``pip`` для установки Pipenv:" @@ -19286,29 +20013,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" -msgstr "" +msgstr "Примечания" -#: ../source/tutorials/packaging-projects.rst:547 -#, fuzzy +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -892,7 +1029,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1029,145 +1166,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1175,46 +1319,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1222,26 +1366,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1558,24 +1702,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1584,22 +1732,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1607,7 +1755,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1616,43 +1764,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1743,14 +1891,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1758,11 +1907,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1771,11 +1920,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1784,67 +1933,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1853,7 +2003,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1861,7 +2011,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1869,21 +2019,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1893,48 +2043,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1942,11 +2092,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1955,17 +2105,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1981,12 +2129,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2145,7 +2293,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2214,14 +2362,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2577,8 +2725,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2753,6 +2900,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2761,14 +2916,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2776,36 +2931,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2826,14 +2981,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2873,11 +3028,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2885,7 +3040,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2893,16 +3048,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2912,256 +3067,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3171,78 +3138,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3251,24 +3179,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3277,7 +3205,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3289,13 +3217,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3303,12 +3231,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3316,69 +3244,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3386,42 +3273,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3429,58 +3316,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3488,44 +3375,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3535,17 +3422,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3554,13 +3441,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3570,7 +3457,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3578,21 +3465,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3601,22 +3488,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3624,23 +3511,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3649,11 +3536,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3661,95 +3548,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3757,7 +3644,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3765,7 +3652,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3774,7 +3661,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3784,78 +3671,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3863,7 +3750,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3871,14 +3758,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3992,96 +3871,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4096,9 +3966,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4380,7 +4250,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4485,6 +4355,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4513,7 +4384,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4689,7 +4560,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4748,33 +4619,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4782,146 +4653,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4929,106 +4800,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5477,13 +5348,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5553,7 +5423,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5592,11 +5462,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6213,11 +6083,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6226,19 +6096,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6249,17 +6119,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6267,17 +6137,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6285,7 +6155,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6293,7 +6163,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6302,27 +6172,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6330,11 +6200,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6342,13 +6212,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6356,11 +6226,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6369,21 +6239,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6391,17 +6261,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6413,19 +6283,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6434,13 +6304,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6734,44 +6604,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6779,39 +6657,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6820,52 +6698,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7618,8 +7496,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7736,89 +7614,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7826,129 +7741,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8383,8 +8349,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8395,9 +8361,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8456,13 +8421,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8475,18 +8439,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8495,18 +8459,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8517,42 +8481,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8561,22 +8525,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8584,15 +8548,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8601,14 +8565,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8621,17 +8585,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8639,17 +8603,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8661,17 +8625,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8682,34 +8646,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8717,44 +8681,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8763,18 +8727,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8785,17 +8749,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8803,17 +8767,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8823,17 +8787,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8843,17 +8807,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8863,18 +8827,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8885,18 +8849,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8924,7 +8888,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8943,24 +8907,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8968,21 +8932,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8990,17 +8954,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10373,25 +10337,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10402,86 +10358,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10490,35 +10413,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10526,32 +10449,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10559,41 +10482,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10602,14 +10525,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10617,7 +10540,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10625,33 +10548,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10659,25 +10582,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10688,63 +10611,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10752,71 +10675,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10824,28 +10747,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10854,22 +10777,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10877,29 +10800,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10909,7 +10832,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10917,25 +10840,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10943,99 +10866,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11044,38 +10921,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11083,7 +10960,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11091,18 +10968,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11111,7 +10988,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11122,7 +10999,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11140,7 +11017,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11149,70 +11026,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11314,41 +11188,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11356,20 +11230,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11377,27 +11251,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11405,19 +11291,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11425,7 +11311,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11433,7 +11319,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11441,31 +11327,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11579,91 +11465,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11673,11 +11559,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11685,43 +11571,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11729,64 +11615,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11794,13 +11680,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11808,36 +11694,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11846,13 +11732,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11860,20 +11746,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11881,7 +11767,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11891,11 +11777,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11903,7 +11789,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11913,18 +11799,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11933,7 +11819,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11944,63 +11830,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12011,33 +11897,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12046,3347 +11932,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15394,7 +15275,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15403,11 +15284,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15418,21 +15299,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15444,7 +15325,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15455,7 +15336,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15467,41 +15348,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15509,7 +15390,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15517,58 +15398,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15576,7 +15457,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15584,13 +15465,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15599,7 +15480,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15608,18 +15489,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15627,7 +15508,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15637,11 +15518,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15649,15 +15530,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15665,11 +15546,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15677,29 +15558,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15708,11 +15589,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15720,14 +15601,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15736,7 +15617,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15870,10 +15751,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16043,22 +15924,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16066,7 +15947,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16074,19 +15955,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16094,24 +15975,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16119,26 +16000,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16146,7 +16027,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16154,63 +16035,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16218,11 +16099,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16231,7 +16112,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16241,7 +16122,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16250,7 +16131,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16258,23 +16139,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16288,7 +16169,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16296,7 +16177,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16308,36 +16189,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16345,21 +16226,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16367,35 +16252,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16403,48 +16288,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16452,7 +16337,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16460,11 +16345,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16472,11 +16357,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16484,20 +16369,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16506,13 +16391,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16522,28 +16407,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16554,14 +16439,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16569,22 +16454,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16593,11 +16478,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16607,11 +16492,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16621,11 +16506,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16633,11 +16518,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16648,11 +16533,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16660,11 +16545,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16672,11 +16557,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16686,11 +16571,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16698,11 +16583,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16710,11 +16595,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16722,11 +16607,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16735,11 +16620,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16748,11 +16633,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16762,7 +16647,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16770,69 +16655,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16840,48 +16725,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16892,7 +16777,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16902,17 +16787,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16921,18 +16806,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16943,7 +16828,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16951,30 +16836,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16982,30 +16867,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17013,60 +16898,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17075,79 +16960,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17156,7 +17041,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17164,31 +17049,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17196,7 +17081,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17205,7 +17090,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17215,14 +17100,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17231,28 +17116,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17261,27 +17146,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17291,7 +17176,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17301,13 +17186,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17526,7 +17411,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17534,7 +17419,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17545,15 +17430,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17561,7 +17446,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17569,7 +17454,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17581,43 +17466,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17626,20 +17511,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18941,28 +18826,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Sinhala `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -896,7 +1033,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1033,145 +1170,152 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 msgid "``python setup.py --version``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1179,46 +1323,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1226,26 +1370,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1562,24 +1706,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1588,22 +1736,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1611,7 +1759,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1620,43 +1768,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1747,14 +1895,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1762,11 +1911,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1775,11 +1924,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1788,67 +1937,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1857,7 +2007,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1865,7 +2015,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1873,21 +2023,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1897,48 +2047,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1946,11 +2096,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1959,17 +2109,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -1985,12 +2133,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2149,7 +2297,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2218,14 +2366,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2581,8 +2729,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2757,6 +2904,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2765,14 +2920,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2780,36 +2935,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2830,14 +2985,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2877,11 +3032,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2889,7 +3044,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2897,16 +3052,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2916,256 +3071,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3175,78 +3142,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3255,24 +3183,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3281,7 +3209,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3293,13 +3221,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3307,12 +3235,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3320,69 +3248,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3390,42 +3277,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3433,58 +3320,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3492,44 +3379,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3539,17 +3426,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3558,13 +3445,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3574,7 +3461,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3582,21 +3469,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3605,22 +3492,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3628,23 +3515,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3653,11 +3540,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3665,95 +3552,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3761,7 +3648,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3769,7 +3656,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3778,7 +3665,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3788,78 +3675,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3867,7 +3754,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3875,14 +3762,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -3996,96 +3875,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4100,9 +3970,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4384,7 +4254,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4489,6 +4359,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4517,7 +4388,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4693,7 +4564,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4752,33 +4623,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4786,146 +4657,146 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 msgid "Install a package" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 msgid "Install a specific package version" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 msgid "Install extras" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 msgid "Install a package from source" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4933,106 +4804,106 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 msgid "Install from other package indexes" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5481,13 +5352,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5557,7 +5427,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5596,11 +5466,11 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6217,11 +6087,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6230,19 +6100,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6253,17 +6123,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6271,17 +6141,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6289,7 +6159,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6297,7 +6167,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6306,27 +6176,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6334,11 +6204,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6346,13 +6216,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6360,11 +6230,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6373,21 +6243,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6395,17 +6265,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6417,19 +6287,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6438,13 +6308,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6738,44 +6608,52 @@ msgstr "" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6783,39 +6661,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6824,52 +6702,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7622,8 +7500,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7740,89 +7618,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7830,129 +7745,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8387,8 +8353,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8399,9 +8365,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8460,13 +8425,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8479,18 +8443,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8499,18 +8463,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8521,42 +8485,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8565,22 +8529,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8588,15 +8552,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8605,14 +8569,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8625,17 +8589,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8643,17 +8607,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8665,17 +8629,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8686,34 +8650,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8721,44 +8685,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8767,18 +8731,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8789,17 +8753,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8807,17 +8771,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8827,17 +8791,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8847,17 +8811,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8867,18 +8831,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8889,18 +8853,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8928,7 +8892,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8947,24 +8911,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -8972,21 +8936,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -8994,17 +8958,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10377,25 +10341,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10406,86 +10362,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10494,35 +10417,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10530,32 +10453,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10563,41 +10486,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10606,14 +10529,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10621,7 +10544,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10629,33 +10552,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10663,25 +10586,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10692,63 +10615,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10756,71 +10679,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10828,28 +10751,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10858,22 +10781,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10881,29 +10804,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10913,7 +10836,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10921,25 +10844,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -10947,99 +10870,53 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 -msgid "" -"This specification does not have an opinion on how you should organize your " -"code. The .data directory is just a place for any files that are not " -"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " -"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " -"though *those* files will usually not be distributed in *wheel's* ``.data`` " -"directory." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11048,38 +10925,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11087,7 +10964,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11095,18 +10972,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11115,7 +10992,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11126,7 +11003,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11144,7 +11021,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11153,70 +11030,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11318,41 +11192,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11360,20 +11234,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11381,27 +11255,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11409,19 +11295,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11429,7 +11315,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11437,7 +11323,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11445,31 +11331,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11583,91 +11469,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11677,11 +11563,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11689,43 +11575,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11733,64 +11619,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11798,13 +11684,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11812,36 +11698,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11850,13 +11736,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11864,20 +11750,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11885,7 +11771,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11895,11 +11781,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11907,7 +11793,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11917,18 +11803,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11937,7 +11823,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -11948,63 +11834,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12015,33 +11901,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12050,3347 +11936,3342 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:223 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 -msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:17 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 -msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:51 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 -msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:68 +msgid "" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:24 +msgid "" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:52 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 -msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 -msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:116 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"An error except when defined by the context interpreting the specification." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:11 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:14 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:51 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:64 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:68 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:73 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:130 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 -msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 -msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:148 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:167 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:240 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:249 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:32 -msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:88 -msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:105 -msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:40 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "pyproject type" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 -msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -msgid "Implementation Notes" +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/index.rst:6 -msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -msgid "pyproject type" +#: ../source/specifications/platform-compatibility-tags.rst:157 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -msgid "Reference Implementation" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15398,7 +15279,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15407,11 +15288,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15422,21 +15303,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15448,7 +15329,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15459,7 +15340,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15471,41 +15352,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15513,7 +15394,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15521,58 +15402,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15580,7 +15461,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15588,13 +15469,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15603,7 +15484,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15612,18 +15493,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15631,7 +15512,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15641,11 +15522,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15653,15 +15534,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15669,11 +15550,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15681,29 +15562,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15712,11 +15593,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15724,14 +15605,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15740,7 +15621,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15874,10 +15755,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16047,22 +15928,22 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 msgid "Definitions" msgstr "" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16070,7 +15951,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16078,19 +15959,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16098,24 +15979,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16123,26 +16004,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16150,7 +16031,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16158,63 +16039,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16222,11 +16103,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16235,7 +16116,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16245,7 +16126,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16254,7 +16135,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16262,23 +16143,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16292,7 +16173,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16300,7 +16181,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16312,36 +16193,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16349,21 +16230,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16371,35 +16256,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16407,48 +16292,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16456,7 +16341,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16464,11 +16349,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16476,11 +16361,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16488,20 +16373,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16510,13 +16395,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16526,28 +16411,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16558,14 +16443,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16573,22 +16458,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16597,11 +16482,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16611,11 +16496,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16625,11 +16510,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16637,11 +16522,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16652,11 +16537,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16664,11 +16549,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16676,11 +16561,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16690,11 +16575,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16702,11 +16587,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16714,11 +16599,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16726,11 +16611,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16739,11 +16624,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16752,11 +16637,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16766,7 +16651,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16774,69 +16659,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16844,48 +16729,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16896,7 +16781,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16906,17 +16791,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -16925,18 +16810,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -16947,7 +16832,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -16955,30 +16840,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -16986,30 +16871,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17017,60 +16902,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17079,79 +16964,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17160,7 +17045,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17168,31 +17053,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17200,7 +17085,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17209,7 +17094,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17219,14 +17104,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17235,28 +17120,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17265,27 +17150,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17295,7 +17180,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17305,13 +17190,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17530,7 +17415,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17538,7 +17423,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17549,15 +17434,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17565,7 +17450,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17573,7 +17458,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17585,43 +17470,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17630,20 +17515,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18945,28 +18830,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Slovak `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -999,7 +1136,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1138,147 +1275,154 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:104 -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy #| msgid "Python version" msgid "``python setup.py --version``" msgstr "Verzia Pythonu" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 -msgid "``python -m setuptools-scm``" +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 msgid "``easy_install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 msgid "``install_headers``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1286,46 +1430,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1333,26 +1477,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1669,24 +1813,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1695,22 +1843,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1718,7 +1866,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1727,43 +1875,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1854,14 +2002,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1869,11 +2018,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1882,11 +2031,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1895,67 +2044,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Projekt" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1964,7 +2114,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1972,7 +2122,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1980,21 +2130,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2004,48 +2154,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2053,11 +2203,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2066,17 +2216,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2092,12 +2240,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2256,7 +2404,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2325,14 +2473,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2688,8 +2836,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2864,6 +3011,14 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2872,14 +3027,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2887,36 +3042,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2937,14 +3092,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2984,11 +3139,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2996,7 +3151,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3004,16 +3159,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3023,256 +3178,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3282,78 +3249,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3362,24 +3290,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3388,7 +3316,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3400,13 +3328,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3414,12 +3342,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3427,69 +3355,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3497,42 +3384,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3540,58 +3427,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3599,44 +3486,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3646,17 +3533,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3665,13 +3552,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3681,7 +3568,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3689,21 +3576,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3712,22 +3599,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3735,23 +3622,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3760,11 +3647,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3772,95 +3659,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3868,7 +3755,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3876,7 +3763,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3885,7 +3772,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3895,78 +3782,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Vytvoriť účet" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3974,7 +3861,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3982,14 +3869,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4103,96 +3982,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4207,9 +4077,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4491,7 +4361,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4596,6 +4466,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4624,7 +4495,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4802,7 +4673,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4861,33 +4732,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4895,156 +4766,156 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "Inštalovanie balíčkov" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "Inštalovanie balíčkov" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "Installing packages" msgid "Install a specific package version" msgstr "Inštalovanie balíčkov" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy #| msgid "Translations" msgid "Install extras" msgstr "Preklady" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing packages" msgid "Install a package from source" msgstr "Inštalovanie balíčkov" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5052,108 +4923,108 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing packages" msgid "Install from other package indexes" msgstr "Inštalovanie balíčkov" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5604,13 +5475,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5680,7 +5550,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5719,11 +5589,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "Meno projektu" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6340,11 +6212,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6353,19 +6225,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6376,17 +6248,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6394,17 +6266,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6412,7 +6284,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6420,7 +6292,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6429,27 +6301,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6457,11 +6329,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6469,13 +6341,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6483,11 +6355,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6496,21 +6368,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6518,17 +6390,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6540,19 +6412,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6561,13 +6433,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6863,44 +6735,52 @@ msgstr "Preklady" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6908,39 +6788,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6949,52 +6829,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7747,8 +7627,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7865,89 +7745,126 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7955,129 +7872,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8512,8 +8480,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8524,9 +8492,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8585,13 +8552,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8604,18 +8570,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8624,18 +8590,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8646,42 +8612,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8690,22 +8656,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8713,15 +8679,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8730,14 +8696,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8750,17 +8716,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8768,17 +8734,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8790,17 +8756,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8811,34 +8777,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8846,44 +8812,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8892,18 +8858,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8914,17 +8880,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8932,17 +8898,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8952,17 +8918,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8972,17 +8938,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8992,18 +8958,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9014,18 +8980,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9053,7 +9019,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9072,24 +9038,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9097,21 +9063,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9119,17 +9085,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10502,25 +10468,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10531,86 +10489,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10619,35 +10544,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10655,32 +10580,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10688,41 +10613,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10731,14 +10656,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10746,7 +10671,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10754,33 +10679,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10788,25 +10713,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10817,63 +10742,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10881,71 +10806,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10953,28 +10878,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10983,22 +10908,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11006,29 +10931,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11038,7 +10963,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11046,25 +10971,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11072,85 +10997,39 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 -msgid "Wheel defines a .data directory. Should I put all my data there?" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11160,11 +11039,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11173,38 +11052,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11212,7 +11091,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11220,18 +11099,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11240,7 +11119,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11251,7 +11130,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11269,7 +11148,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11278,70 +11157,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11443,41 +11319,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11485,20 +11361,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11506,27 +11382,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11534,19 +11422,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11554,7 +11442,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11562,7 +11450,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11570,31 +11458,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11708,91 +11596,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Udržiavač" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11802,11 +11690,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11814,43 +11702,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11858,64 +11746,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11923,13 +11811,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11937,36 +11825,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11975,13 +11863,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11989,20 +11877,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12010,7 +11898,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12020,11 +11908,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12032,7 +11920,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12042,18 +11930,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12062,7 +11950,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12073,63 +11961,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12140,33 +12028,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12175,3355 +12063,3350 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 -msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:148 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" +#: ../source/specifications/dependency-specifiers.rst:155 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:219 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 -msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 -msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:8 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:17 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:36 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" +#: ../source/specifications/direct-url-data-structure.rst:34 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 -msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" -msgstr "" - -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:14 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:19 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:24 -msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:32 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:42 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." -msgstr "" - -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:73 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:88 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:138 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:153 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:158 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 -msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 -msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 -msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "Inštalovanie balíčkov" + +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 -msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:177 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:206 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 -msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Typy dokumentov" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:101 -msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/index.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +#| msgid "Project name" +msgid "pyproject type" +msgstr "Meno projektu" + +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "Installing packages" -msgid "Python-specific package manager" -msgstr "Inštalovanie balíčkov" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Typy dokumentov" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:177 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 -msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" +msgstr "" + +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Typy dokumentov" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:79 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 -msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." -msgstr "" - -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "Project name" -msgid "pyproject type" -msgstr "Meno projektu" - -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Typy dokumentov" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 -msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:178 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:190 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" - -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" + +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:39 -msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:211 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:215 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:226 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:247 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:254 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:275 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:284 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 -msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 -msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 -msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:61 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:87 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:96 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pypirc.rst:131 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 -msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 -msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:44 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:105 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 -msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:155 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 -msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:170 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:239 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:242 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 +#: ../source/specifications/pyproject-toml.rst:278 msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:281 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 -msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:340 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15531,7 +15414,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15540,11 +15423,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15555,21 +15438,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15581,7 +15464,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15592,7 +15475,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15604,41 +15487,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15646,7 +15529,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15654,58 +15537,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15713,7 +15596,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15721,13 +15604,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15736,7 +15619,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15745,18 +15628,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15764,7 +15647,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15774,11 +15657,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15786,15 +15669,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15802,11 +15685,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15814,29 +15697,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15845,11 +15728,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15857,14 +15740,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15873,7 +15756,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16007,10 +15890,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16180,24 +16063,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Špecifikácie" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16205,7 +16088,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16213,19 +16096,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16233,24 +16116,24 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 msgid "Version scheme" msgstr "" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16258,26 +16141,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16285,7 +16168,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16293,63 +16176,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16357,11 +16240,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16370,7 +16253,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16380,7 +16263,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16389,7 +16272,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16397,23 +16280,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16427,7 +16310,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16435,7 +16318,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16447,36 +16330,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16484,21 +16367,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16506,35 +16393,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16542,48 +16429,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16591,7 +16478,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16599,11 +16486,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16611,11 +16498,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16623,20 +16510,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16645,13 +16532,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16661,28 +16548,28 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 msgid "Version epochs" msgstr "" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16693,14 +16580,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16708,22 +16595,22 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 msgid "Integer Normalization" msgstr "" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16732,11 +16619,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16746,11 +16633,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16760,11 +16647,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16772,11 +16659,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16787,11 +16674,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16799,11 +16686,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16811,11 +16698,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16825,11 +16712,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16837,11 +16724,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16849,11 +16736,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16861,11 +16748,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16874,11 +16761,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16887,11 +16774,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16901,7 +16788,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16909,69 +16796,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16979,48 +16866,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17031,7 +16918,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17041,17 +16928,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17060,18 +16947,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17082,7 +16969,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17090,30 +16977,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17121,30 +17008,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17152,60 +17039,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17214,79 +17101,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17295,7 +17182,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17303,31 +17190,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17335,7 +17222,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17344,7 +17231,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17354,14 +17241,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17370,28 +17257,28 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 msgid "Version exclusion" msgstr "" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17400,27 +17287,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17430,7 +17317,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17440,13 +17327,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17665,7 +17552,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17673,7 +17560,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17684,15 +17571,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17700,7 +17587,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17708,7 +17595,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17720,43 +17607,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17765,20 +17652,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19080,28 +18967,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages \n" "Language-Team: Ukrainian `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "Import Package" +msgid "What's an import package?" +msgstr "Імпорт пакету" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -1145,7 +1288,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1296,173 +1439,180 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "Так (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "Так (``python -m pip uninstall``)" #: ../source/discussions/setup-py-deprecated.rst:105 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "Так (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy #| msgid "``python_requires``" msgid "``python setup.py --version``" msgstr "``python_requires``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy #| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "Так (``python -m pip uninstall``)" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 #, fuzzy msgid "``bdist``" msgstr "``text/x-rst``" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 #, fuzzy #| msgid "build" msgid "``build``" msgstr "build" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 #, fuzzy msgid "``build_scripts``" msgstr "``scripts``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy #| msgid "**easy_install**" msgid "``easy_install``" msgstr "**easy_install**" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 #, fuzzy #| msgid "``pip install app``" msgid "``install``" msgstr "``pip install app``" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 #, fuzzy #| msgid "``pip install app``" msgid "``install_data``" msgstr "``pip install app``" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 #, fuzzy #| msgid "``install_requires``" msgid "``install_egg_info``" msgstr "``install_requires``" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy #| msgid "``install_requires``" msgid "``install_headers``" msgstr "``install_requires``" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 #, fuzzy #| msgid "``install_requires``" msgid "``install_lib``" msgstr "``install_requires``" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 #, fuzzy #| msgid "``console_scripts``" msgid "``install_scripts``" msgstr "``console_scripts``" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 #, fuzzy #| msgid "``scripts``" msgid "``saveopts``" msgstr "``scripts``" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1470,48 +1620,48 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 #, fuzzy #| msgid "pyproject.toml" msgid "Is ``pyproject.toml`` mandatory?" msgstr "pyproject.toml" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1519,26 +1669,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1889,24 +2039,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1915,22 +2069,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1938,7 +2092,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1947,43 +2101,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -2074,14 +2228,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Яйце" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -2089,11 +2244,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "Модуль розширення" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -2102,11 +2257,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -2115,67 +2270,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "Імпорт пакету" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "Модуль" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "Реєстр Пакунків" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "Індекс за проєктом" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "Проєкт" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2184,7 +2340,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2192,7 +2348,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -2200,21 +2356,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "Чистий модуль" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "Управління з пакування Python (PyPA)" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2224,48 +2380,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "Реєстр Python-пакунків (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "Випуск" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2273,11 +2429,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2286,17 +2442,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "Специфікатор вимоги" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2312,12 +2466,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2476,7 +2630,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2547,14 +2701,14 @@ msgid "Column" msgstr "Стовпець" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "Опис" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "Приклади" @@ -2916,8 +3070,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -3092,6 +3245,16 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2013-12-08" +msgid "2023-12-14" +msgstr "08.12.2013" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -3100,14 +3263,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -3115,36 +3278,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -3165,14 +3328,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rst / README.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -3212,11 +3375,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -3224,7 +3387,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3232,16 +3395,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3251,256 +3414,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``name``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "``version``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "``url``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "``author``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "``license``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "``classifiers``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "``keywords``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -msgid "``project_urls``" -msgstr "``project_urls``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3510,78 +3485,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "``install_requires``" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "``python_requires``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3590,24 +3526,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3616,7 +3552,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3628,13 +3564,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3642,12 +3578,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "``scripts``" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3655,69 +3591,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" -msgstr "" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" +msgstr "Вибір схеми версіонування" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "``console_scripts``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "Вибір схеми версіонування" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "Ось кілька прикладів сумісних номерів версій::" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3725,42 +3620,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "Семантичне версіонування (надається перевага)" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3768,41 +3663,41 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "Версіонування базоване на датах" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "Порядкове версіонування" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." @@ -3810,18 +3705,18 @@ msgstr "" "Це найпростіша з можливих схем версіонування, яка складається з єдиного " "числа, яке збільшується при кожній публікації." -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3829,44 +3724,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "Версіонування попередніх випусків" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "Ідентифікатори місцевих версій" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3876,17 +3771,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3895,13 +3790,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3911,7 +3806,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3919,21 +3814,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3942,22 +3837,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3965,23 +3860,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3990,11 +3885,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -4002,95 +3897,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -4098,7 +3993,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -4106,7 +4001,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -4115,7 +4010,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -4125,78 +4020,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "Створіть обліковий запис" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -4204,7 +4099,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -4212,14 +4107,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4333,96 +4220,89 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +#, fuzzy +#| msgid "Examples::" +msgid "Examples:" msgstr "Приклади::" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4437,9 +4317,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4721,7 +4601,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4826,6 +4706,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "Наприклад:" @@ -4854,7 +4735,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -5033,7 +4914,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -5096,33 +4977,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -5130,155 +5011,155 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "Installing packages" msgid "Install a specific package version" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy msgid "Install extras" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing packages" msgid "Install a package from source" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5286,110 +5167,110 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing packages" msgid "Install from other package indexes" msgstr "Встановлення пакунків" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy #| msgid "Requirements files" msgid "Using a requirements file" msgstr "Файли requirements" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5846,14 +5727,12 @@ msgstr "Дистриб'юторський пакет" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -#, fuzzy -msgid ":ref:`declaring-build-dependencies`" -msgstr "``dependencies``/``optional-dependencies``" +msgid ":ref:`pyproject-build-system-table`" +msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5927,7 +5806,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5966,11 +5845,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "pyproject.toml" +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6589,11 +6470,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6602,19 +6483,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6625,17 +6506,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6643,17 +6524,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6661,7 +6542,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6669,7 +6550,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6678,29 +6559,29 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 #, fuzzy #| msgid ":file:`setup.cfg`" msgid "Or :file:`setup.py`:" msgstr ":file:`setup.cfg`" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6708,11 +6589,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6720,13 +6601,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6734,11 +6615,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6747,21 +6628,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6769,17 +6650,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6791,19 +6672,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6812,13 +6693,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -7116,44 +6997,52 @@ msgstr "Формат встановлення" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -7161,39 +7050,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -7202,52 +7091,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -8000,8 +7889,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -8120,91 +8009,128 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "``version``" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy #| msgid "install_requires vs requirements files" msgid "Dependencies and requirements" msgstr "install_requires проти файлів requirements" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "``dependencies``/``optional-dependencies``" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "``requires-python``" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -8212,131 +8138,182 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "``authors``/``maintainers``" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "``readme``" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "``urls``" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 #, fuzzy #| msgid "For example:" msgid "A full example" msgstr "Наприклад:" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8775,8 +8752,8 @@ msgstr "pipx" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8787,9 +8764,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8850,13 +8826,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8869,18 +8844,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "twine" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8889,18 +8864,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "virtualenv" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8911,42 +8886,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "Warehouse" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "wheel" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8955,22 +8930,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "buildout" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8978,15 +8953,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "conda" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8995,14 +8970,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -9015,17 +8990,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "devpi" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -9033,17 +9008,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "enscons" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -9055,17 +9030,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "Hashdist" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -9076,34 +9051,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -9111,46 +9086,46 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "multibuild" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy #| msgid "`pip-tools `_" msgid "`GitHub `__" msgstr "`pip-tools `_" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -9159,18 +9134,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "pip-tools" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -9181,17 +9156,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "piwheels" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -9199,17 +9174,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "poetry" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -9219,17 +9194,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "pypiserver" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -9239,17 +9214,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9259,18 +9234,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "scikit-build" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9281,20 +9256,20 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 #, fuzzy #| msgid "scikit-build" msgid "scikit-build-core" msgstr "scikit-build" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9322,7 +9297,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9341,24 +9316,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "zest.releaser" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9366,21 +9341,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "ensurepip" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9388,17 +9363,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "venv" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10775,25 +10750,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10804,86 +10771,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "Обґрунтування" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10892,35 +10826,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10928,32 +10862,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10961,41 +10895,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "дистрибутив" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "Назва розповсюджуваного пакунка, наприклад, 'django', 'pyramid'." -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "Версія розповсюджуваного пакунка, наприклад, 1.0." -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -11004,14 +10938,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -11019,7 +10953,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -11027,33 +10961,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "Реалізація мови та теґ версії" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "Наприклад, 'py27', 'py2', 'py3'." -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "Наприклад, 'cp33m', 'abi3', 'none'." -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "Наприклад, 'linux_x86_64', 'any'." -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -11061,25 +10995,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -11090,63 +11024,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -11154,71 +11088,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -11226,28 +11160,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11256,22 +11190,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11279,29 +11213,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11311,7 +11245,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11319,25 +11253,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11345,15 +11279,15 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" @@ -11361,72 +11295,26 @@ msgid "" msgstr "" "https://self-issued.info/docs/draft-jones-jose-jws-json-serialization.html" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "https://self-issued.info/docs/draft-jones-jose-json-private-key.html" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "ЧаПи" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11436,11 +11324,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11449,38 +11337,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11488,7 +11376,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11496,18 +11384,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11516,7 +11404,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11527,7 +11415,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11545,7 +11433,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11554,70 +11442,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" -msgstr "Зміни" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." +msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "Додаток" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "Авторське право" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "Цей документ передано у суспільне надбання." - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "``Metadata-Version``" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "``Name``" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "``Version``" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "Усі інші поля необов'язкові." -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "Приклад::" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "Name" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11719,41 +11604,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "Version" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11761,20 +11646,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11782,27 +11667,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "Приклади::" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11810,19 +11707,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "Підсумок" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11830,7 +11727,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11838,7 +11735,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11846,31 +11743,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11984,91 +11881,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "Author" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "Author-email" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "Доглядач" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "Maintainer-email" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "License" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -12078,11 +11975,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -12090,43 +11987,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -12134,64 +12031,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -12199,13 +12096,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -12213,36 +12110,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12251,13 +12148,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12265,20 +12162,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12286,7 +12183,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12296,11 +12193,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12308,7 +12205,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12318,18 +12215,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12338,7 +12235,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12349,65 +12246,65 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 #, fuzzy #| msgid "Requirements files" msgid "Requires" msgstr "Файли requirements" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12418,33 +12315,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12453,3400 +12350,3397 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "Специфікація" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "Специфікація" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 -msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -#, fuzzy -msgid "``authors``" -msgstr "``author``" - -#: ../source/specifications/declaring-project-metadata.rst:55 -#, fuzzy -msgid "``dependencies``" -msgstr "Перевизначення залежностей" - -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" -msgstr "``dynamic``" - -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -#, fuzzy -msgid "``gui-scripts``" -msgstr "``scripts``" - -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "Доглядач" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:64 +#: ../source/specifications/dependency-specifiers.rst:132 #, fuzzy -msgid "``optional-dependencies``" -msgstr "``dependencies``/``optional-dependencies``" - -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" -msgstr "" +msgid "Names" +msgstr "Name" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "Version" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:183 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +#: ../source/specifications/dependency-specifiers.rst:219 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Версія Python" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:236 +#, fuzzy +msgid "``os_name``" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:237 +#, fuzzy +msgid "``os.name``" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 +#: ../source/specifications/dependency-specifiers.rst:255 +#, fuzzy +msgid "``platform_version``" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:256 +#, fuzzy +msgid "``platform.version()``" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "``version``" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "``python_requires``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:268 +#, fuzzy +msgid "``cpython``" +msgstr "``description``" + +#: ../source/specifications/dependency-specifiers.rst:269 +#, fuzzy +msgid "``implementation_version``" +msgstr "Реалізація мови та теґ версії" + +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:273 +msgid "" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 +#: ../source/specifications/dependency-specifiers.rst:275 +#, fuzzy +msgid "``test``" +msgstr "``text/x-rst``" + +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 -msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/direct-url.rst:8 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/direct-url.rst:17 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/direct-url.rst:24 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:29 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:36 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "``pip install https://example.com/app-1.0.tgz``" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "``pip install https://example.com/app-1.0.whl``" + +#: ../source/specifications/direct-url.rst:51 +#, fuzzy +msgid "" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" +"``pip install \"git+https://example.com/repo/app." +"git#egg=app&subdirectory=setup\"``" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" +msgstr "``pip install ./app``" + +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" +msgstr "``pip install file:///home/user/app``" + +#: ../source/specifications/direct-url.rst:54 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "``pip install -e ./app``" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "``pip install app``" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "``pip install app --no-index --find-links https://example.com/``" + +#: ../source/specifications/direct-url.rst:68 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url-data-structure.rst:31 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url-data-structure.rst:34 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url-data-structure.rst:42 +msgid "" +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url-data-structure.rst:49 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -#, fuzzy -msgid "Names" -msgstr "Name" - -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 -msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "Version" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:82 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:88 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:91 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:95 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:102 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:105 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 -msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Версія Python" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -#, fuzzy -msgid "``os_name``" -msgstr "``name``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -#, fuzzy -msgid "``os.name``" -msgstr "``name``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" +msgstr "Git" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" +msgstr "Домашня сторінка" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 -msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" +msgstr "git" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" +msgstr "Mercurial" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "hg" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" +msgstr "Bazaar" -#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/direct-url-data-structure.rst:181 #, fuzzy -msgid "``platform_version``" -msgstr "``version``" +#| msgid "https://www.mercurial-scm.org/" +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.mercurial-scm.org/" -#: ../source/specifications/dependency-specifiers.rst:254 -#, fuzzy -msgid "``platform.version()``" -msgstr "``version``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" +msgstr "bzr" -#: ../source/specifications/dependency-specifiers.rst:255 -msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "``version``" - -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" +msgstr "Subversion" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "``python_requires``" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" +msgstr "https://subversion.apache.org/" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" -msgstr "" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" +msgstr "svn" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:212 +msgid "" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -#, fuzzy -msgid "``cpython``" -msgstr "``description``" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -#, fuzzy -msgid "``implementation_version``" -msgstr "Реалізація мови та теґ версії" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:268 +msgid "" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"An error except when defined by the context interpreting the specification." +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -#, fuzzy -msgid "``test``" -msgstr "``text/x-rst``" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/entry-points.rst:7 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/entry-points.rst:11 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" -msgstr "" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Модель даних" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/entry-points.rst:32 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/entry-points.rst:42 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 +#: ../source/specifications/entry-points.rst:51 msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:68 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:8 -msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/entry-points.rst:82 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 +#: ../source/specifications/entry-points.rst:88 msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:98 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:101 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:105 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" -msgstr "``pip install https://example.com/app-1.0.tgz``" - -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" -msgstr "``pip install https://example.com/app-1.0.whl``" - -#: ../source/specifications/direct-url.rst:51 -#, fuzzy +#: ../source/specifications/entry-points.rst:138 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -"``pip install \"git+https://example.com/repo/app." -"git#egg=app&subdirectory=setup\"``" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" -msgstr "``pip install ./app``" - -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" -msgstr "``pip install file:///home/user/app``" - -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:145 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" -msgstr "" - -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" -msgstr "``pip install -e ./app``" - -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" -msgstr "" - -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" -msgstr "``pip install app``" - -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" -msgstr "``pip install app --no-index --find-links https://example.com/``" - -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:153 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 -msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 -msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +#| msgid "distribution" +msgid "distro" +msgstr "дистрибутив" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "пакунок" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "Встановлення пакунків" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 -msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 -msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +#| msgid "PyPA specifications" +msgid "This specification is twofold." +msgstr "Специфікації PyPA" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" -msgstr "Git" - -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" -msgstr "Домашня сторінка" - -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" -msgstr "https://git-scm.com/" - -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" -msgstr "git" - -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:162 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:170 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" -msgstr "Mercurial" - -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" -msgstr "hg" - -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" -msgstr "Bazaar" - -#: ../source/specifications/direct-url-data-structure.rst:189 -#, fuzzy -#| msgid "https://www.mercurial-scm.org/" -msgid "https://www.breezy-vcs.org/" -msgstr "https://www.mercurial-scm.org/" - -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" -msgstr "bzr" - -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" -msgstr "Subversion" - -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" -msgstr "https://subversion.apache.org/" - -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" -msgstr "svn" - -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:206 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:230 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:262 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:266 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:273 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/entry-points.rst:11 -msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:279 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +#| msgid "Create a new project." +msgid "Guide users towards virtual environments" +msgstr "Створіть новий проєкт." + +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" -msgstr "Модель даних" +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:310 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/entry-points.rst:42 -msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:319 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/entry-points.rst:68 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:349 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:393 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:396 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" -msgstr "Наприклад::" - -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Типи документації" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:143 -msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +#| msgid "``pip install app``" +msgid "``pip install``" +msgstr "``pip install app``" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:156 -msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +#| msgid "``pip install -e ./app``" +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install -e ./app``" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 -msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +#| msgid "``pip install -e ./app``" +msgid "``pip install --user``" +msgstr "``pip install -e ./app``" -#: ../source/specifications/externally-managed-environments.rst:13 -msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -#, fuzzy -#| msgid "distribution" -msgid "distro" -msgstr "дистрибутив" - -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 -msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Авторське право" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 -msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -msgid "package" -msgstr "пакунок" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Специфікації PyPA" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/index.rst:6 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 -msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "Installing packages" -msgid "Python-specific package manager" -msgstr "Встановлення пакунків" - -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:33 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:59 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:62 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -#, fuzzy -#| msgid "PyPA specifications" -msgid "This specification is twofold." -msgstr "Специфікації PyPA" - -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" -msgstr "" +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +#| msgid "pyproject.toml" +msgid "pyproject type" +msgstr "pyproject.toml" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/inline-script-metadata.rst:108 +#, fuzzy +msgid "Example" +msgstr "Приклади" + +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Типи документації" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 +#: ../source/specifications/inline-script-metadata.rst:231 +#, fuzzy +#| msgid "Packaging tool recommendations" +msgid "Recommendations" +msgstr "Поради щодо засобу пакування" + +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 +#: ../source/specifications/name-normalization.rst:5 +#, fuzzy +msgid "Package name normalization" +msgstr "Версія пакунку" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 #, fuzzy -#| msgid "Create a new project." -msgid "Guide users towards virtual environments" -msgstr "Створіть новий проєкт." +msgid "Normalization" +msgstr "Переклади" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:26 +#, fuzzy +msgid "'py27', 'cp33'" +msgstr "Наприклад, 'py27', 'py2', 'py3'." + +#: ../source/specifications/platform-compatibility-tags.rst:28 +#, fuzzy +msgid "'cp32dmu', 'none'" +msgstr "Наприклад, 'cp33m', 'abi3', 'none'." + +#: ../source/specifications/platform-compatibility-tags.rst:30 #, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "Типи документації" +msgid "'linux_x86_64', 'any'" +msgstr "Наприклад, 'linux_x86_64', 'any'." -#: ../source/specifications/externally-managed-environments.rst:412 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -#, fuzzy -#| msgid "``pip install app``" -msgid "``pip install``" -msgstr "``pip install app``" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:55 #, fuzzy -#| msgid "``pip install -e ./app``" -msgid "``pip install --prefix=/some/path``" -msgstr "``pip install -e ./app``" +msgid "cp: CPython" +msgstr "``description``" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -#, fuzzy -#| msgid "``pip install -e ./app``" -msgid "``pip install --user``" -msgstr "``pip install -e ./app``" +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 -msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" -msgstr "Специфікації PyPA" - -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 -msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 -msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 -msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 -msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:102 +#, fuzzy +msgid "linux_x86_64" +msgstr "Наприклад, 'linux_x86_64', 'any'." -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:107 +#, fuzzy +msgid "``manylinux``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" - -#: ../source/specifications/inline-script-metadata.rst:81 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:137 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" +msgstr "Інструмент" -#: ../source/specifications/inline-script-metadata.rst:108 -#, fuzzy -msgid "Example" -msgstr "Приклади" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" +msgstr "``manylinux1``" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "Типи документації" - -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Packaging tool recommendations" -msgid "Recommendations" -msgstr "Поради щодо засобу пакування" +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -#, fuzzy -msgid "Package name normalization" -msgstr "Версія пакунку" +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "Переклади" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:238 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:44 -msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -#, fuzzy -msgid "'py27', 'cp33'" -msgstr "Наприклад, 'py27', 'py2', 'py3'." - -#: ../source/specifications/platform-compatibility-tags.rst:28 -#, fuzzy -msgid "'cp32dmu', 'none'" -msgstr "Наприклад, 'cp33m', 'abi3', 'none'." - -#: ../source/specifications/platform-compatibility-tags.rst:30 -#, fuzzy -msgid "'linux_x86_64', 'any'" -msgstr "Наприклад, 'linux_x86_64', 'any'." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:289 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:294 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/platform-compatibility-tags.rst:300 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "Файл :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -#, fuzzy -msgid "cp: CPython" -msgstr "``description``" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:96 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -#, fuzzy -msgid "linux_x86_64" -msgstr "Наприклад, 'linux_x86_64', 'any'." +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 +#: ../source/specifications/pyproject-toml.rst:6 #, fuzzy -msgid "``manylinux``" -msgstr "``manylinux1``" +#| msgid "pyproject.toml" +msgid "``pyproject.toml`` specification" +msgstr "pyproject.toml" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" -msgstr "Інструмент" - -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" -msgstr "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" -msgstr "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" -msgstr "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" -msgstr "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" -msgstr "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:132 +#, fuzzy +msgid "``authors``" +msgstr "``author``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" -msgstr "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:134 +#, fuzzy +msgid "``dependencies``" +msgstr "Перевизначення залежностей" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" -msgstr "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" +msgstr "``dynamic``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" -msgstr "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "auditwheel" +#: ../source/specifications/pyproject-toml.rst:138 +#, fuzzy +msgid "``gui-scripts``" +msgstr "``scripts``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "Доглядач" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" -msgstr "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:143 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" -msgstr "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" -msgstr "Файл :file:`.pypirc`" - -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15854,7 +15748,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15863,11 +15757,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15878,21 +15772,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15904,7 +15798,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15915,7 +15809,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15927,41 +15821,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15969,7 +15863,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15977,58 +15871,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "Файл METADATA" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "Файл RECORD" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -16036,7 +15930,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -16044,13 +15938,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -16059,7 +15953,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -16068,18 +15962,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -16087,7 +15981,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -16097,11 +15991,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "Файл INSTALLER" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -16109,15 +16003,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -16125,11 +16019,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -16137,29 +16031,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -16168,11 +16062,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -16180,14 +16074,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -16196,7 +16090,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16332,10 +16226,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16505,24 +16399,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "Специфікації" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16530,7 +16424,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16538,19 +16432,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16558,25 +16452,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "Version" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16584,28 +16478,28 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy #| msgid "Local version identifiers" msgid "Public version identifiers" msgstr "Ідентифікатори місцевих версій" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16613,7 +16507,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16621,63 +16515,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16685,11 +16579,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16698,7 +16592,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16708,7 +16602,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16717,7 +16611,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16725,23 +16619,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16755,7 +16649,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16763,7 +16657,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16775,36 +16669,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16812,21 +16706,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "Наприклад::" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16834,37 +16732,37 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy #| msgid "Pre-release versioning" msgid "Pre-releases" msgstr "Версіонування попередніх випусків" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16872,50 +16770,50 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy #| msgid "zest.releaser" msgid "Post-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16923,7 +16821,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16931,11 +16829,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16943,11 +16841,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16955,20 +16853,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16977,13 +16875,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16993,29 +16891,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "Version" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -17026,14 +16924,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -17041,23 +16939,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "Переклади" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -17066,13 +16964,13 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 #, fuzzy #| msgid "Pre-release versioning" msgid "Pre-release separators" msgstr "Версіонування попередніх випусків" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -17082,13 +16980,13 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 #, fuzzy #| msgid "Pre-release versioning" msgid "Pre-release spelling" msgstr "Версіонування попередніх випусків" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -17098,11 +16996,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -17110,11 +17008,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -17125,13 +17023,13 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 #, fuzzy #| msgid "Pre-release versioning" msgid "Post release spelling" msgstr "Версіонування попередніх випусків" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -17139,11 +17037,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -17151,11 +17049,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -17165,11 +17063,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -17177,11 +17075,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -17189,13 +17087,13 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 #, fuzzy #| msgid "Local version identifiers" msgid "Local version segments" msgstr "Ідентифікатори місцевих версій" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -17203,11 +17101,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -17216,11 +17114,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -17229,13 +17127,13 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 #, fuzzy #| msgid "Here are some examples of compliant version numbers::" msgid "Examples of compliant version schemes" msgstr "Ось кілька прикладів сумісних номерів версій::" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -17245,7 +17143,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -17253,71 +17151,71 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 #, fuzzy #| msgid "Serial versioning" msgid "Simple \"major.minor\" versioning::" msgstr "Порядкове версіонування" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17325,48 +17223,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17377,7 +17275,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17387,17 +17285,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17406,20 +17304,20 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 #, fuzzy #| msgid "Serial versioning" msgid "Semantic versioning" msgstr "Порядкове версіонування" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17430,7 +17328,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17438,32 +17336,32 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 #, fuzzy #| msgid "Date based versioning" msgid "DVCS based version labels" msgstr "Версіонування базоване на датах" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17471,32 +17369,32 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 #, fuzzy #| msgid "Date based versioning" msgid "Olson database versioning" msgstr "Версіонування базоване на датах" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17504,60 +17402,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17566,81 +17464,81 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy #| msgid "Version" msgid "Version matching" msgstr "Version" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17649,7 +17547,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17657,31 +17555,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17689,7 +17587,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17698,7 +17596,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17708,14 +17606,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17724,30 +17622,30 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy #| msgid "Version Specifier" msgid "Version exclusion" msgstr "Специфікатор версії" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17756,27 +17654,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17786,7 +17684,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17796,13 +17694,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -18021,7 +17919,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -18029,7 +17927,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -18040,17 +17938,17 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 #, fuzzy #| msgid "For example::" msgid "Remote URL examples::" msgstr "Наприклад::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -18058,7 +17956,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -18066,7 +17964,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -18078,43 +17976,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -18123,20 +18021,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19461,28 +19359,32 @@ msgstr "" "На цьому етапі, якщо ви бажаєте почитати більше про пакування Python-" "бібліотек, то ось що ви можете зробити:" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "Прочитайте про :doc:`/guides/packaging-binary-extensions`." +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages , 2023. # xiTiRuoLiWong , 2023. # Eric , 2023. +# Autuamn End , 2023. +# Thomas , 2023. msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" -"PO-Revision-Date: 2023-11-21 07:03+0000\n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" +"PO-Revision-Date: 2023-12-18 06:41+0000\n" "Last-Translator: Eric \n" "Language-Team: Chinese (Simplified) \n" @@ -36,7 +38,7 @@ msgstr "" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" -"X-Generator: Weblate 5.2\n" +"X-Generator: Weblate 5.3\n" #: ../source/contribute.rst:5 msgid "Contribute to this guide" @@ -92,10 +94,6 @@ msgstr "文档类型" #: ../source/contribute.rst:34 #, fuzzy -#| msgid "" -#| "This project consists of four distinct documentation types with specific " -#| "purposes. When proposing new additions to the project please pick the " -#| "appropriate documentation type." msgid "" "This project consists of four distinct documentation types with specific " "purposes. The project aspires to follow the `Diátaxis process`_ for creating " @@ -179,9 +177,6 @@ msgstr "" #: ../source/contribute.rst:80 #, fuzzy -#| msgid "" -#| "If you are experiencing issues while you are working on translations, " -#| "please open an issue on `Github`_." msgid "" "If you are experiencing issues while you are working on translations, please " "open an issue on `GitHub`_." @@ -579,6 +574,7 @@ msgid "Deploying Python applications" msgstr "部署 Python 应用程序" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/migrating-to-pypi-org.rst:0 @@ -597,6 +593,7 @@ msgid "Incomplete" msgstr "不完全" #: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 #: ../source/guides/index-mirrors-and-caches.rst:0 #: ../source/guides/installing-using-linux-tools.rst:0 #: ../source/guides/packaging-binary-extensions.rst:0 @@ -659,11 +656,6 @@ msgstr "" #: ../source/discussions/deploying-python-applications.rst:71 #, fuzzy -#| msgid "" -#| "A big advantage of Pynsist is that the Windows packages can be built on " -#| "Linux. There are several examples for different kinds of programs " -#| "(console, GUI) in the `documentation `. The tool is " -#| "released under the MIT-licence." msgid "" "A big advantage of Pynsist is that the Windows packages can be built on " "Linux. There are several examples for different kinds of programs (console, " @@ -726,7 +718,7 @@ msgid "Unix (including Linux and macOS)" msgstr "Unix（包括 Linux 和 macOS）" #: ../source/discussions/deploying-python-applications.rst:118 -#: ../source/key_projects.rst:532 +#: ../source/key_projects.rst:531 msgid "pex" msgstr "pex" @@ -750,6 +742,143 @@ msgstr "" msgid "Configuration management" msgstr "配置管理" +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution package vs. import package" +msgstr "发行版" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "什么是分发包？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject." +"toml``, ``pkg`` is the name of a distribution package. When you search or " +"browse the PyPI_, the most widely known centralized source for installing " +"Python libraries and tools, what you see is a list of distribution packages. " +"Alternatively, the term \"distribution package\" can be used to refer to a " +"specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "什么是导入包？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -1051,11 +1180,11 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:6 msgid "Is ``setup.py`` deprecated?" -msgstr "" +msgstr "``setup.py``被弃用了吗？" #: ../source/discussions/setup-py-deprecated.rst:8 msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." -msgstr "" +msgstr "不，:term:`setup.py`和:ref:`setuptools`并没有被弃用。" #: ../source/discussions/setup-py-deprecated.rst:10 msgid "" @@ -1063,7 +1192,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1093,7 +1222,6 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:39 #: ../source/guides/modernize-setup-py-project.rst:36 #, fuzzy -#| msgid "``python_version``" msgid "``python setup.py sdist``" msgstr "``python_version``" @@ -1115,27 +1243,24 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:33 #: ../source/guides/modernize-setup-py-project.rst:30 #, fuzzy -#| msgid "Creating Documentation" msgid "Recommendation" -msgstr "创建文档" +msgstr "建议" #: ../source/discussions/setup-py-deprecated.rst:35 #: ../source/guides/modernize-setup-py-project.rst:32 -#, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m pip install .``" -msgstr "有(``python -m pip uninstall``)" +msgstr "``python -m pip install .``" #: ../source/discussions/setup-py-deprecated.rst:37 #: ../source/guides/modernize-setup-py-project.rst:34 #, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" msgid "``python -m pip install --editable .``" -msgstr "有(``python -m pip uninstall``)" +msgstr "``python -m pip install --editable .``" #: ../source/discussions/setup-py-deprecated.rst:39 +#, fuzzy msgid "``python -m build`` [#needs-build]_" -msgstr "" +msgstr "``python -m build`` [#needs-build]_" #: ../source/discussions/setup-py-deprecated.rst:45 msgid "" @@ -1191,7 +1316,6 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:91 #, fuzzy -#| msgid "``python_version``" msgid "``python setup.py test``" msgstr "``python_version``" @@ -1211,172 +1335,167 @@ msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 #, fuzzy -#| msgid "``python -m build``" -msgid "``python -m twine check``" +msgid "``python -m twine check --strict dist/*``" msgstr "``python -m build``" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy -#| msgid "Yes (``python -m pip uninstall``)" -msgid "``python -m twine register``" -msgstr "有(``python -m pip uninstall``)" +#| msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "``python -m twine register``" #: ../source/discussions/setup-py-deprecated.rst:105 #, fuzzy -#| msgid "``python -m build``" -msgid "``python -m twine upload``" +msgid "``python -m twine upload dist/*``" msgstr "``python -m build``" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy -#| msgid "``python_version``" msgid "``python setup.py --version``" msgstr "``python_version``" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy -#| msgid "``python -m build``" -msgid "``python -m setuptools-scm``" -msgstr "``python -m build``" +#| msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools-scm``" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 #, fuzzy -#| msgid "build" msgid "``build``" msgstr "建造" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 #, fuzzy -#| msgid "``gui-scripts``" msgid "``build_scripts``" msgstr "``gui-scripts``" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 #, fuzzy -#| msgid "``pypinfo``" msgid "``dist_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy -#| msgid "**easy_install**" msgid "``easy_install``" msgstr "**easy_install**" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 #, fuzzy -#| msgid "``pypinfo``" msgid "``egg_info``" msgstr "``pypinfo``" -#: ../source/discussions/setup-py-deprecated.rst:141 -#, fuzzy -#| msgid "``pip install``" +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" -msgstr "``pip install``" +msgstr "``install``" -#: ../source/discussions/setup-py-deprecated.rst:142 -#, fuzzy -#| msgid "``pip install``" +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" -msgstr "``pip install``" +msgstr "``install_data``" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 #, fuzzy msgid "``install_egg_info``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy msgid "``install_headers``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 #, fuzzy msgid "``install_lib``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 #, fuzzy msgid "``install_scripts``" msgstr "install_requires" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1384,46 +1503,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "``pyproject.toml`` 是强制性的吗？" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1431,26 +1550,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1809,24 +1928,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "源代码分发（sdist）" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1835,22 +1958,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr ":ref:`build`包知道如何调用你的构建工具来创建其中一个：" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "或者，你的构建工具可能提供自己的接口来创建sdist。" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "构建分发（wheels）" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1858,7 +1981,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1867,43 +1990,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "上传到包分发服务" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "下载并安装" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1995,6 +2118,15 @@ msgstr "" "存档文件是最终用户将从 Internet 下载并安装的文件。" #: ../source/glossary.rst:64 +#, fuzzy +#| msgid "" +#| "A distribution package is more commonly referred to with the single words " +#| "\"package\" or \"distribution\", but this guide may use the expanded term " +#| "when more clarity is needed to prevent confusion with an :term:`Import " +#| "Package` (which is also commonly called a \"package\") or another kind of " +#| "distribution (e.g. a Linux distribution or the Python language " +#| "distribution), which are often referred to with the single term " +#| "\"distribution\"." msgid "" "A distribution package is more commonly referred to with the single words " "\"package\" or \"distribution\", but this guide may use the expanded term " @@ -2002,17 +2134,18 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" "分发包更常被称为“包”或“分发”，但是当需要更清楚地防止与 :term:`Import " "Package` 混淆时，本指南可能会使用扩展术语（通常也称为“包”）或另一种发行版（例" "如 Linux 发行版或 Python 语言发行版），通常用单个术语“发行版”来指代。" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "Egg" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -2024,11 +2157,11 @@ msgstr "" "python_eggs>` 和 `Python Eggs `_" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "扩展模块" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -2041,11 +2174,11 @@ msgstr "" "享对象 (.so) 文件、Windows 上 Python 扩展的 DLL（给定 .pyd 扩展）或 Jython 扩" "展的 Java 类文件。" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "已知良好集 (KGS)" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -2057,31 +2190,38 @@ msgstr "" "包被声明为已知良好集之前通过所有测试。 该术语通常用于由多个单独发行版组成的框" "架和工具包。" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "导入包" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "一个Python模块，可以包含其他模块或递归地包含其他包。" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 +#, fuzzy +#| msgid "" +#| "An import package is more commonly referred to with the single word " +#| "\"package\", but this guide will use the expanded term when more clarity " +#| "is needed to prevent confusion with a :term:`Distribution Package` which " +#| "is also commonly called a \"package\"." msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" "导入包通常用单个词“包”来指代，但本指南将在需要更清楚地说明时使用扩展术语，以" "防止与通常也称为“包”的 :term:`分发包` 混淆." -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "模块" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." @@ -2089,11 +2229,11 @@ msgstr "" "Python 中代码可重用性的基本单元，存在于以下两种类型之一：:term:`Pure Module` " "或 :term:`Extension Module`。" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "包索引" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." @@ -2101,11 +2241,11 @@ msgstr "" "一个带有 Web 界面的发行版存储库，用于自动化 :term:`package ` 发现和消费。" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "每个项目索引（Per Project Index）" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " @@ -2114,11 +2254,11 @@ msgstr "" "专用或其他非规范的：term:`Package Index`由特定的：term:`Project`表示，作为首" "选索引或解决该项目依赖关系所需的索引。" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "项目" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " @@ -2127,7 +2267,7 @@ msgstr "" "数据或其他资源的库、框架、脚本、插件、应用程序或集合，或其组合，旨在打包成:" "term:`Distribution `。" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -2140,7 +2280,7 @@ msgstr "" "另一个实际方式是在项目源目录下包含 :term:`pyproject.toml`、 :term:`setup.py`" "或 :term:`setup.cfg` 文件的东西。" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -2152,7 +2292,7 @@ msgstr "" "` ，每个版本可能包括一个或多个 :term:`套件 ` 。" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -2163,11 +2303,11 @@ msgstr "" "这并不一定是真的。可以从项目“foo”安装一个发行版，并让它提供一个只能作" "为“bar”导入的包。" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "纯模块 (Pure Module)" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." @@ -2175,11 +2315,11 @@ msgstr "" "一个 :term:`Module`，使用 Python 编写并包含在单个 ``.py`` 文件 中（可能还有相" "关的 ``.pyc`` 和/或者 ``.pyo`` 文件）。" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "Python 包装管理局 （PyPA）" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -2195,11 +2335,11 @@ msgstr "" "和 `Python Discourse 论坛 `__ 上讨论" "问题。" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "Python 包索引 (PyPI)" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " @@ -2208,11 +2348,11 @@ msgstr "" "`PyPI `_ 是 Python 社区的默认 :term:`包索引 (Package " "Index) ` 。所有 Python 开发人员都可以使用和分发他们的发行版。" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "pypi.org" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." @@ -2222,26 +2362,26 @@ msgstr "" "名。它在2017年取代了旧的索引域名， ``pypi.python.org`` ，并由 :ref:" "`warehouse` 提供支持。" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "pyproject.toml" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "发行版 （Release）" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -2249,11 +2389,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "要求 (Requirement)" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -2262,17 +2402,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "需求说明符" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2291,12 +2429,12 @@ msgstr "" "Requirements Files` 。" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "setup.py" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "setup.cfg" @@ -2466,8 +2604,13 @@ msgstr "" "有被下载很多，也不意味着它不好！" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 +#, fuzzy +#| msgid "" +#| "In short, because it's value is low for various reasons, and the " +#| "tradeoffs required to make it work are high, it has been not an effective " +#| "use of limited resources." msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2550,14 +2693,14 @@ msgid "Column" msgstr "列" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "描述" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "例子" @@ -2928,8 +3071,7 @@ msgid "" msgstr "`pandas-gbq`_ 项目允许通过 `Pandas`_ 来访问查询结果。" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "参考" @@ -3108,6 +3250,16 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2013-12-08" +msgid "2023-12-14" +msgstr "2013-12-08" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -3116,14 +3268,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -3131,37 +3283,37 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" "首先，确保你已经满足了 :ref:`安装软件包的要求 `。" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "安装 \"twine\" [1]_:" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "配置你的项目" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "初始文件" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_。" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr ":file:`setup.py` 有主要有两个功能：" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -3186,14 +3338,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "README.rst / README.md" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText `_ 的多种变体（请看 ``setup()`` 的 :ref:" "`long_description_content_type ` 参数）。" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_ 的 `README.md `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -3245,11 +3397,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "MANIFEST.in" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -3257,7 +3409,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -3268,16 +3420,16 @@ msgstr "" "github.com/pypa/sampleproject>`_ 已经删除了它的清单文件，因为所有必要的文件已" "经被 :ref:`setuptools` 43.0.0 和更新的版本所包含。" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr ":file:`MANIFEST.in`不影响诸如 wheels 这样的二进制发行。" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "LICENSE.txt" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -3291,7 +3443,7 @@ msgstr "" "择哪种许可证，你可以使用诸如 `GitHub 的选择许可证 `_ 等资源，或者咨询律师。" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " @@ -3322,11 +3474,11 @@ msgstr "" "包含的 `sample `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "setup() 参数" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " @@ -3335,83 +3487,31 @@ msgstr "" "如上所述， :file:`setup.py` 的主要特点是它包含一个全局的 ``setup()`` 函数。 " "这个函数的关键字参数规定了如何定义你项目的具体细节。" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" -"最相关的参数解释如下。这里给出的大部分片段来自于 `PyPA样本项目 `_ 中的`setup.py `_ 。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "``name``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" -"这是你的项目名称，这决定了你的项目如何在 :term:`PyPI ` 中列出。 根据 :pep:`508`，有效的项目名称必须是：" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" -"仅由 ASCII 字母、数字、下划线（``_``）、连字符（``-``）和/或句号（``.``）组" -"成，并且" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "以一个 ASCII 字母或数字开始和结束。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" -"项目名称的比较是不分大小写的，并将任意长的下划线、连字符和/或句号视为相等。例" -"如，如果你注册了一个名为 ``cool-stuff`` 的项目，用户可以使用以下任何一种拼写" -"方式下载它或声明对它的依赖::" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -"这是你的项目的当前版本，允许你的用户确定他们是否有最新的版本，并指出他们对自" -"己的软件进行过哪些具体的测试。" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +#, fuzzy +#| msgid "" +#| "The most relevant arguments are explained below. Most of the snippets " +#| "given are taken from the `setup.py `_ contained in " +#| "the `PyPA sample project `_." msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -"如果你发布了你的项目，每个版本都会显示在 :term:`PyPI `上。" +"最相关的参数解释如下。这里给出的大部分片段来自于 `PyPA样本项目 `_ 中的`setup.py `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." @@ -3419,162 +3519,11 @@ msgstr "" "请参阅 :ref:`Choosing a versioning scheme` 了解更多如何使用版本向你的用户传达" "兼容性信息的信息。" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "``description``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "为你的项目提供一个简短和长的描述。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" -"如果你发布你的项目，这些值将显示在 :term:`PyPI `。在``pypi.org``上，用户界面会在灰色横幅上显示``description``，在名" -"为 \"项目描述 \" 的部分显示 ``long_description``。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" -"``description``也会显示在项目列表中。例如，它在搜索结果页面（如 https://pypi." -"org/search/?q=jupyter）、热门项目和新版本的头版列表，以及你在账户资料中维护的" -"项目列表（如 https://pypi.org/user/jaraco/）中可见。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "``url``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "为你的项目提供一个主页 URL 。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -#, fuzzy -msgid "``author``" -msgstr "作者 (author)" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "提供关于作者的详细信息。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "``license``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "``classifiers``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" -"提供对你的项目进行分类的分类器列表。有关完整列表，请参阅 https://pypi.org/" -"classifiers/ 。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "``keywords``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "列出描述你的项目的关键词。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -#, fuzzy -msgid "``project_urls``" -msgstr "project_urls" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "``packages``" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3584,105 +3533,66 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "``py_modules``" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 #, fuzzy msgid "``install_requires``" msgstr "install_requires" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" -#: ../source/guides/distributing-packages-using-setuptools.rst:405 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "以此类推。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 -msgid "``package_data``" -msgstr "``package_data``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:445 -msgid "" -"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " -"package’s implementation, or text files containing documentation that might " -"be of interest to programmers using the package. These files are called " -"\"package data\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "``data_files``" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3691,7 +3601,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3703,13 +3613,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3717,12 +3627,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3730,56 +3640,15 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" -msgstr "``entry_points``" - -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:517 -msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." -msgstr "最常用的入口点是 \"console_scripts\"（见下文）。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 +#: ../source/guides/distributing-packages-using-setuptools.rst:295 msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:552 +#: ../source/guides/distributing-packages-using-setuptools.rst:298 msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:554 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" "Different Python projects may use different versioning schemes based on the " "needs of that particular project, but all of them are required to comply " @@ -3788,11 +3657,11 @@ msgid "" "libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:560 +#: ../source/guides/distributing-packages-using-setuptools.rst:306 msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3800,42 +3669,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3843,58 +3712,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3902,33 +3771,33 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." @@ -3936,12 +3805,12 @@ msgstr "" "``pip`` 和其他现代的 Python 软件包安装程序在决定安装哪些版本的依赖项时，默认" "会忽略预发布版本（pre-releases）。" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "本地版本标识符" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3951,17 +3820,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "在 「开发模式」(development mode) 下工作" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3970,13 +3839,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3986,7 +3855,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3994,21 +3863,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -4017,22 +3886,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -4040,23 +3909,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -4065,11 +3934,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -4077,95 +3946,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "将你的项目上传到 PyPI" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -4173,7 +4042,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -4181,7 +4050,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -4190,7 +4059,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -4200,11 +4069,11 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "创建一个账户" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website ` 用户账户。你可以 " "`使用 PyPI 网站上的表格创建一个账户 `_ 。" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "现在你将创建一个PyPI `API 令牌`_ ，这样你就能安全地上传你的项目。" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " @@ -4228,13 +4097,13 @@ msgstr "" "到 https://pypi.org/manage/account/#api-tokens 上创建一个新的 `API token`_ ；" "不要把其范围限制在一个特定的项目上，因为你正在创建一个新的项目。" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "**在复制和保存令牌之前不要关闭页面──你不会再看到该令牌。**" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" @@ -4242,23 +4111,23 @@ msgstr "" "为了避免每次上传时都要复制和粘贴令牌，你可以创建一个 :file:`$HOME/.pypirc`文" "件：" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "**请注意，这将以明文形式存储你的令牌。**" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "有关更多详细信息，请参见 :ref:`规格 ` for :file:`.pypirc`。" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "上传你的发行版" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." @@ -4266,7 +4135,7 @@ msgstr "" "一旦你有了账户，你就可以使用 :ref:`twine`将你的发行版上传到 :term:`PyPI " "`。" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " @@ -4275,14 +4144,14 @@ msgstr "" "无论项目是否已经存在于 PyPI 上，上传发布版的过程都是一样的——如果它还不存在，" "那么在上传第一个发布版时，它将被自动创建。" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" "对于第二个及以后的版本，PyPI 只要求新版本的版本号与以前的任何版本不同。" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -4293,7 +4162,7 @@ msgstr "" "件包是否已经成功上传，其中 ``sampleproject`` 是你上传项目的名称。你的项目可能" "需要一两分钟才能出现在网站上。" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -4304,14 +4173,6 @@ msgstr "" "户安装（user installs）成为默认行为`_ 来改变这一点。" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "放弃对旧版 Python 的支持" @@ -4427,96 +4288,87 @@ msgstr "" "本。" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" -msgstr "例子::" +msgid "Examples:" +msgstr "例子:" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "3. 发布前验证元数据（Metadata）" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "你可以看到生成文件的内容是这样的：" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "4. 使用 Twine 来发布" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "确保你正在使用最新的 Twine 版本，至少为1.9。" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "放弃一个 Python 版本" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "例如，你发布了 Requires-Python: \">=2.7\" 作为你软件包的 1.0.0 版本。" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4531,9 +4383,9 @@ msgstr "托管你自己的简单存储库" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4574,9 +4426,6 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:57 #, fuzzy -#| msgid "" -#| "For complete documentation of the simple repository protocol, see :pep:" -#| "`503`." msgid "" "For complete documentation of the simple repository protocol, see :ref:" "`simple repository API `." @@ -4824,7 +4673,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4948,6 +4797,7 @@ msgstr "" "现在你可以用 ``pipx install`` 来安装软件包，并从任何地方运行软件包的程序。" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "例如：" @@ -4978,7 +4828,8 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "要查看 pipx提供的全部命令列表，请运行：" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#, fuzzy +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "要了解 pipx 的更多信息，可以访问 https://pypa.github.io/pipx/。" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -5154,12 +5005,11 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 #, fuzzy -#| msgid "Creating a virtual environment" msgid "Create and activate a virtual environment" msgstr "创建一个虚拟环境" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -5169,7 +5019,6 @@ msgstr "使用 ``pip`` 命令将软件包安装到虚拟环境" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 #, fuzzy -#| msgid "install_requires vs requirements files" msgid "Use and create a requirements file" msgstr "install_requires 与 requirements files" @@ -5196,13 +5045,11 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 #, fuzzy -#| msgid "Creating a virtual environment" msgid "Create and Use Virtual Environments" msgstr "创建一个虚拟环境" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 #, fuzzy -#| msgid "Creating a virtual environment" msgid "Create a new virtual environment" msgstr "创建一个虚拟环境" @@ -5223,15 +5070,20 @@ msgid "" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 +#, fuzzy +#| msgid "" +#| "To create a virtual environment, go to your project's directory and run " +#| "``venv``. This will create a new virtual environment in a local folder ``." +#| "venv``:" msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" "要创建虚拟环境，转到项目目录并运行 ``venv``。这会在本地环境中创建新的虚拟环境" "``.venv``:" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." @@ -5239,15 +5091,13 @@ msgstr "" "第二个参数是创建虚拟环境的位置。一般来说，你可以直接在你的项目中创建它，并称" "之为 ``.venv`` 。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 #, fuzzy -#| msgid "" -#| "venv will create a virtual Python installation in the ``env`` folder." msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "venv 将在 ``env`` 文件夹中创建一个虚拟的 Python 安装。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." @@ -5255,19 +5105,13 @@ msgstr "" "你应该使用 ``.gitignore`` 或类似的方法将你的虚拟环境目录从你的版本控制系统中" "排除。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 #, fuzzy -#| msgid "Activating a virtual environment" msgid "Activate a virtual environment" msgstr "激活一个虚拟环境" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 #, fuzzy -#| msgid "" -#| "Before you can start installing or using packages in your virtual " -#| "environment you'll need to *activate* it. Activating a virtual " -#| "environment will put the virtual environment-specific ``python`` and " -#| "``pip`` executables into your shell's ``PATH``." msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -5277,28 +5121,21 @@ msgstr "" "在你开始安装或使用虚拟环境中的软件包之前，你需要 *激活* 它。激活虚拟环境将把" "虚拟环境专用的 ``python`` 和 ``pip`` 可执行文件放入你的 shell 的 ``PATH`` 。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 #, fuzzy -#| msgid "" -#| "You can confirm you're in the virtual environment by checking the " -#| "location of your Python interpreter:" msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "你可以通过检查你的 Python 解释器的位置来确认你在虚拟环境中：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 #, fuzzy -#| msgid "" -#| "As long as your virtual environment is activated pip will install " -#| "packages into that specific environment and you'll be able to import and " -#| "use packages in your Python application." msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " @@ -5307,48 +5144,43 @@ msgstr "" "只要你的虚拟环境被激活，pip 就会将软件包安装到该特定环境中，你就可以在你的 " "Python 应用程序中导入和使用软件包。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 #, fuzzy -#| msgid "Activating a virtual environment" msgid "Deactivate a virtual environment" msgstr "激活一个虚拟环境" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 #, fuzzy -#| msgid "" -#| "If you want to switch projects or otherwise leave your virtual " -#| "environment, simply run:" msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "如果你想切换项目或以其他方式离开你的虚拟环境，只需运行：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 #, fuzzy -#| msgid "Activating a virtual environment" msgid "Reactivate a virtual environment" msgstr "激活一个虚拟环境" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " @@ -5357,46 +5189,41 @@ msgstr "" "macOS的 Python 安装程序包括 pip。在 Linux 系统上，你或许必需安装额外的软件" "包，如 ``python3-pip``。你可以运行下列命令确保 pip 为最新：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "在此之后，最新版本的 pip 应该被安装在你的用户站点上：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" "Windows 的 Python 安装程序包括 pip。你可以运行下列命令确保 pip 为最新：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "之后，你应该有最新版本的 pip ：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 msgid "Install packages using pip" msgstr "用 pip 安装软件包" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" "激活虚拟环境后，你可以安装软件包。使用 ``pip install``命令来安装软件包。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy -#| msgid "Installing packages" msgid "Install a package" msgstr "安装软件包（英文）" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 #, fuzzy -#| msgid "" -#| "Now that you're in your virtual environment you can install packages. " -#| "Let's install the `Requests`_ library from the :term:`Python Package " -#| "Index (PyPI)`:" msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" @@ -5404,18 +5231,17 @@ msgstr "" "现在你在你的虚拟环境中，你可以安装软件包。让我们从 :term:`Python Package " "Index (PyPI)` 中安装 `Requests`_ 库：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "pip应该下载 request 及其所有的依赖项并安装它们：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy -#| msgid "Installing specific versions" msgid "Install a specific package version" msgstr "安装特定版本" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " @@ -5424,21 +5250,20 @@ msgstr "" "pip 允许你使用 :term:`版本指定器 `来指定安装哪个版本的软件" "包。例如，要安装一个特定版本的 ``requests``：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "要安装最新的 ``2.x`` 版本的 requests：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "要安装预发布（pre-release）版本的软件包，请使用 ``--pre`` 标志：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy -#| msgid "Installing extras" msgid "Install extras" msgstr "安装附加功能" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" @@ -5446,17 +5271,13 @@ msgstr "" "有些软件包有可选的 `extras`_ 。你可以在括号中指定额外的东西来告诉 pip 安装它" "们：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy -#| msgid "Installing from source" msgid "Install a package from source" msgstr "从源文件安装" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 #, fuzzy -#| msgid "" -#| "pip can install packages directly from their version control system. For " -#| "example, you can install directly from a git repository:" msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" @@ -5464,7 +5285,7 @@ msgstr "" "pip 可以直接从他们的版本控制系统中安装软件包。例如，你可以直接从 git 仓库中安" "装：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -5475,13 +5296,12 @@ msgstr "" "源码安装软件包，这意味着源码目录的变化将立即影响已安装的软件包，而不需要重新" "安装：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 #, fuzzy -#| msgid "Installing from version control systems" msgid "Install from version control systems" msgstr "从版本控制系统进行安装" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" @@ -5489,7 +5309,7 @@ msgstr "" "pip 可以直接从他们的版本控制系统中安装软件包。例如，你可以直接从 git 仓库中安" "装：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." @@ -5497,26 +5317,25 @@ msgstr "" "关于支持的版本控制系统和语法的更多信息，请参见 pip 的文档：:ref:`VCS Support " "` 。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 #, fuzzy -#| msgid "Installing from source" msgid "Install from local archives" msgstr "从源文件安装" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " @@ -5525,13 +5344,12 @@ msgstr "" "如果你在一个连接性有限的系统上安装软件包，或者你想严格控制发行软件包的来源，" "这很有用。" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy -#| msgid "Using other package indexes" msgid "Install from other package indexes" msgstr "使用其他软件包的索引" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" @@ -5539,58 +5357,57 @@ msgstr "" "如果你想从不同的索引下载软件包，而不是 :term:`Python 软件包索引（PyPI）` ，你" "可以使用 ``--index-url`` 标志：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "升级软件包" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 #, fuzzy -#| msgid "Requirements files" msgid "Using a requirements file" msgstr "必需文件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "Pip 可以使用 ``freeze`` 命令来导出所有已安装软件包及其版本的列表：" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5993,7 +5810,6 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:10 #, fuzzy -#| msgid "Is ``pyproject.toml`` mandatory?" msgid "Should ``pyproject.toml`` be added?" msgstr "``pyproject.toml`` 是强制性的吗？" @@ -6064,13 +5880,12 @@ msgstr ":ref:`distributing-packages`" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -6140,7 +5955,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -6179,11 +5994,12 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6568,7 +6384,6 @@ msgstr "" #: ../source/guides/packaging-binary-extensions.rst:236 #, fuzzy -#| msgid "Extension Module" msgid "Extension module lifecycle" msgstr "扩展模块" @@ -6804,11 +6619,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6817,19 +6632,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6840,17 +6655,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6858,17 +6673,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6876,7 +6691,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6884,7 +6699,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6893,27 +6708,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6921,11 +6736,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6933,13 +6748,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6947,11 +6762,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6960,21 +6775,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6982,17 +6797,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -7004,19 +6819,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -7025,13 +6840,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -7215,7 +7030,6 @@ msgstr "" #: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:146 #, fuzzy -#| msgid "Publishing the distribution to PyPI and TestPyPI" msgid "Publishing the distribution to PyPI" msgstr "在 PyPI 和 TestPyPI 上发布发行版" @@ -7325,7 +7139,6 @@ msgstr "" #: ../source/guides/section-install.rst:3 #, fuzzy -#| msgid "Installation format" msgid "Installation" msgstr "安装格式" @@ -7333,44 +7146,52 @@ msgstr "安装格式" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -7378,39 +7199,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -7419,52 +7240,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -8226,8 +8047,8 @@ msgstr "在 :file:`.pypirc` 中设置 TestPyPI" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -8344,91 +8165,133 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"项目名称必须由 ASCII 字母、数字、下划线 \"``_``\"、连字符 \"``-``\" 和英文句" +"号 \"``.``\"组。名字开头结尾不能是下划线、连字符或句号。" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"项目名称的比较是不分大小写的，并将任意长的下划线、连字符和/或句号视为相等。例" +"如，如果你注册了一个名为 ``cool-stuff`` 的项目，用户可以使用以下任何一种拼写" +"方式下载它或声明对它的依赖:``Cool-Stuff``, ``cool.stuff``, ``COOL_STUFF``, " +"``CoOl__-.-__sTuFF``." + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 msgid "Put the version of your project." msgstr "输入项目版本。" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 #, fuzzy -#| msgid "install_requires vs requirements files" msgid "Dependencies and requirements" msgstr "install_requires 与 requirements files" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -8436,134 +8299,183 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 #, fuzzy -#| msgid "Configuring your project" msgid "About your project" msgstr "配置你的项目" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." -msgstr "" +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → `reStructuredText `_ (没有 Sphinx扩展）。" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 #, fuzzy -#| msgid "You can see the contents of the generated file like this:" msgid "You can also specify the format explicitly, like this:" msgstr "你可以看到生成文件的内容是这样的：" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" "应用到项目的 PyPI 分类器列表。查看 `可能性的完整列表 `_." -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "完整示例" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8593,10 +8505,6 @@ msgstr "" #: ../source/index.rst:29 #, fuzzy -#| msgid "" -#| "This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " -#| "Authority `. We happily accept any :doc:`contributions and " -#| "feedback `. 😊" msgid "" "This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " "Authority `. We happily accept :doc:`contributions and feedback " @@ -8607,7 +8515,6 @@ msgstr "" #: ../source/index.rst:36 #, fuzzy -#| msgid "Overview" msgid "Overview and Flow" msgstr "总览" @@ -8642,9 +8549,6 @@ msgstr "" #: ../source/index.rst:62 #, fuzzy -#| msgid "" -#| "To learn how to install packages, see the :doc:`tutorial on installing " -#| "packages `" msgid "" "A :doc:`tutorial on installing packages `" msgstr "" @@ -8659,9 +8563,6 @@ msgstr "" #: ../source/index.rst:65 #, fuzzy -#| msgid "" -#| "To learn how to package and distribute your projects, see the :doc:" -#| "`tutorial on packaging and distributing `" msgid "" "A :doc:`tutorial on packaging and distributing ` your project" @@ -8703,7 +8604,6 @@ msgstr "" #: ../source/index.rst:89 #, fuzzy -#| msgid "References" msgid "Reference" msgstr "参考" @@ -8715,9 +8615,6 @@ msgstr "" #: ../source/index.rst:92 #, fuzzy -#| msgid "" -#| "Additionally, there is a list of :doc:`other projects ` " -#| "maintained by members of the Python Packaging Authority." msgid "" "The list of :doc:`other projects ` maintained by members of " "the Python Packaging Authority." @@ -8771,10 +8668,6 @@ msgstr "建造" #: ../source/key_projects.rst:37 #, fuzzy -#| msgid "" -#| "`Docs ` | `Issues `__ " -#| "| `GitHub `__ | `PyPI `__" msgid "" ":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" "`文档< `__ | `GitHub `__ | `PyPI `__" @@ -9076,10 +8970,14 @@ msgstr "" "件包产生依赖性冲突。" #: ../source/key_projects.rst:247 +#, fuzzy +#| msgid "" +#| ":doc:`Docs ` | `Issues `__ | `GitHub `__" msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" ":doc:`文档 ` | `Issues `__ | `GitHub `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -9168,11 +9065,11 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "twine" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -9182,7 +9079,7 @@ msgstr "" "com/pypa/twine/issues>`__ | `GitHub `__ | " "`PyPI `__" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -9191,16 +9088,12 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "virtualenv" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 #, fuzzy -#| msgid "" -#| ":doc:`Docs ` | `Issues `__ | `GitHub `__ | " -#| "`PyPI `__" msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `GitHub `__ | `PyPI " "`__" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -9221,11 +9114,11 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "Warehouse" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" @@ -9233,18 +9126,18 @@ msgstr "" "`文档 `__ | `Issues `__ | `GitHub `__" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "wheel" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " @@ -9254,14 +9147,14 @@ msgstr "" "com/pypa/wheel/issues>`__ | `GitHub `__ | " "`PyPI `__" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -9270,15 +9163,15 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "非 PyPA 项目" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "buildout" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `PyPI `__ | `GitHub `__" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -9296,15 +9189,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "conda" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -9313,14 +9206,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -9333,11 +9226,11 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" @@ -9345,7 +9238,7 @@ msgstr "" "`文档 `__ | :gh:`Issues ` " "| `PyPI `__" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -9353,11 +9246,11 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "enscons" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" @@ -9365,7 +9258,7 @@ msgstr "" ":gh:`源码 ` | :gh:`问题 ` | `PyPI " "`__" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -9377,11 +9270,11 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "Hashdist" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" @@ -9389,7 +9282,7 @@ msgstr "" "`文档 `__ | `GitHub `__" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -9400,11 +9293,11 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" @@ -9412,18 +9305,18 @@ msgstr "" "`文档 `__ | `GitHub `__" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "meson-python" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" @@ -9431,7 +9324,7 @@ msgstr "" "`文档 `__ | `GitHub `__" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -9439,28 +9332,27 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "multibuild" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 #, fuzzy -#| msgid "`GitHub `__" msgid "`GitHub `__" msgstr "`GitHub `__" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -9468,13 +9360,13 @@ msgstr "" "`文档 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -9482,7 +9374,7 @@ msgstr "" "`文档 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -9491,11 +9383,11 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "pip-tools" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -9516,11 +9408,11 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "piwheels" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" @@ -9528,7 +9420,7 @@ msgstr "" "`网站 `__ | :doc:`文档 ` | " "`GitHub `__" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -9536,11 +9428,11 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "poetry" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -9548,7 +9440,7 @@ msgstr "" "`文档 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -9562,15 +9454,12 @@ msgstr "" "自己的依赖性解析器。它试图通过本地缓存依赖关系的元数据来加速用户的安装和依赖" "关系的解决。" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "pypiserver" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 #, fuzzy -#| msgid "" -#| "`GitHub and docs `__ | `PyPI " -#| "`__" msgid "" "`GitHub `__ | `PyPI `__" @@ -9578,7 +9467,7 @@ msgstr "" "`GitHub 和文档 `__ | `PyPI " "`__" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -9592,11 +9481,11 @@ msgstr "" "ref:`pip` 下载和安装它们，而不用公开发布。使用 pypiserver 的组织通常既从 " "pypiserver 也从 PyPI 下载软件包。" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" @@ -9604,7 +9493,7 @@ msgstr "" "`文档 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -9614,11 +9503,11 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "scikit-build" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -9639,13 +9528,12 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 #, fuzzy -#| msgid "scikit-build" msgid "scikit-build-core" msgstr "scikit-build" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" @@ -9677,7 +9565,7 @@ msgstr "" "`文档 `__ | `GitHub `__ | `PyPI `__" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -9685,7 +9573,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -9704,18 +9592,18 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" "Spack 不在 PyPI 中（目前），但它不需要安装，从 GitHub 克隆后可以立即使用。" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "zest.releaser" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__ | `PyPI `__" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9733,15 +9621,15 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "ensurepip" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" @@ -9749,7 +9637,7 @@ msgstr "" "`文档 `__ | `问题 `__" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9757,11 +9645,11 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "venv" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" @@ -9769,7 +9657,7 @@ msgstr "" "`文档 `__ | `问题 `__" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -11143,25 +11031,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -11172,86 +11052,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -11260,35 +11107,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -11296,32 +11143,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -11329,41 +11176,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "version" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -11372,14 +11219,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -11387,7 +11234,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -11395,33 +11242,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -11429,25 +11276,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -11458,63 +11305,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -11522,71 +11369,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "Wheel 不包含 setup.py 或 setup.cfg。" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -11594,28 +11441,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "目录 .dist-info" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -11624,22 +11471,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -11647,29 +11494,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr ".data 目录" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -11679,7 +11526,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -11687,25 +11534,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11713,15 +11560,15 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "见" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" @@ -11729,72 +11576,26 @@ msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "与 .egg 的比较" - -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 +#: ../source/specifications/binary-distribution-format.rst:314 #: ../source/specifications/platform-compatibility-tags.rst:244 msgid "FAQ" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11804,11 +11605,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11817,38 +11618,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11856,7 +11657,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11864,18 +11665,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11884,7 +11685,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11895,7 +11696,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11913,7 +11714,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11922,70 +11723,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 -msgid "" -"The rules on escaping in wheel filenames were revised, to bring them into " -"line with what popular tools actually do (February 2021)." +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" +"The rules on escaping in wheel filenames were revised, to bring them into " +"line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "名称" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -12087,41 +11885,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "版本" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -12129,20 +11927,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -12150,27 +11948,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "例子::" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -12178,19 +11988,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -12198,7 +12008,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -12206,7 +12016,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -12214,31 +12024,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -12352,91 +12162,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "维护者" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -12446,11 +12256,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -12458,43 +12268,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -12502,64 +12312,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -12567,13 +12377,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -12581,36 +12391,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -12619,13 +12429,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -12633,20 +12443,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -12654,7 +12464,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -12664,11 +12474,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -12676,7 +12486,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -12686,18 +12496,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -12706,7 +12516,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12717,65 +12527,64 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 #, fuzzy -#| msgid "Requirements" msgid "Requires" msgstr "要求" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12786,33 +12595,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12821,3366 +12630,3353 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "reStructuredText 标记：https://docutils.sourceforge.io/" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" +msgstr "技术参数" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" -msgstr "技术参数" - -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" -msgstr "``authors``" - -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" -msgstr "``dependencies``" - -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" -msgstr "``entry-points``" - -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" -msgstr "``gui-scripts``" - -#: ../source/specifications/declaring-project-metadata.rst:62 -msgid "``maintainers``" -msgstr "``maintainers``" - -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:128 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" +msgstr "名称" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:134 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:163 +msgid "Versions" +msgstr "版本" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:183 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:186 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:160 +#: ../source/specifications/dependency-specifiers.rst:204 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:216 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 -msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +#: ../source/specifications/dependency-specifiers.rst:234 +msgid "Python equivalent" +msgstr "Python 同等项" + +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" +msgstr "``os_name``" + +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" +msgstr "``os.name``" + +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 -msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``python_version``" +msgstr "``python_version``" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:263 +msgid "``python_full_version``" +msgstr "``python_full_version``" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 -msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 +#: ../source/specifications/dependency-specifiers.rst:273 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 -msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 -msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/dependency-specifiers.rst:497 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:8 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." -msgstr "" - -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 +#: ../source/specifications/direct-url.rst:17 msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 +#: ../source/specifications/direct-url.rst:24 msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:29 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 +#: ../source/specifications/direct-url.rst:36 msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:52 +#, fuzzy +msgid "``pip install ./app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" + +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:54 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" -msgstr "名称" +#: ../source/specifications/direct-url.rst:58 +#, fuzzy +msgid "``pip install -e ./app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" -#: ../source/specifications/dependency-specifiers.rst:132 -msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url.rst:68 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 -msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -msgid "Versions" -msgstr "版本" - -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:13 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:34 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -msgid "Python equivalent" -msgstr "Python 同等项" +#: ../source/specifications/direct-url-data-structure.rst:70 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:73 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" -msgstr "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:76 +msgid "" +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" -msgstr "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" -msgstr "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:95 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:108 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" +msgstr "子目录中的项目" + +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:145 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -msgid "``python_version``" -msgstr "``python_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" -msgstr "``3.4``, ``2.7``" - -#: ../source/specifications/dependency-specifiers.rst:261 -msgid "``python_full_version``" -msgstr "``python_full_version``" - -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:153 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" -msgstr "``3.4.0``, ``3.5.0b1``" - -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" -msgstr "``cpython``" - -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 -msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 -msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 -msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/direct-url.rst:17 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:7 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:11 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:14 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:19 +msgid "" +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:42 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:52 -#, fuzzy -msgid "``pip install ./app``" -msgstr "``pipx`` 是用 ``pip`` 安装的：" - -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:64 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:58 -#, fuzzy -msgid "``pip install -e ./app``" -msgstr "``pipx`` 是用 ``pip`` 安装的：" - -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:62 -#, fuzzy -msgid "``pip install app``" -msgstr "``pipx`` 是用 ``pip`` 安装的：" - -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:82 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 +#: ../source/specifications/entry-points.rst:98 msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/entry-points.rst:101 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/entry-points.rst:105 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/entry-points.rst:138 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 +#: ../source/specifications/entry-points.rst:145 msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/entry-points.rst:153 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "外部管理的环境" + +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +msgid "distro" +msgstr "distlib" + +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "打包" + +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python 软件包管理器" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" -msgstr "子目录中的项目" +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "macOS 安装程序和软件包管理器" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:105 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:170 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:182 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "虚拟环境的 Runtime 检测" + +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "文档类型" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:51 +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:64 -msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." msgstr "" -#: ../source/specifications/entry-points.rst:73 +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/inline-script-metadata.rst:12 +msgid "" +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/inline-script-metadata.rst:20 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/inline-script-metadata.rst:25 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/entry-points.rst:136 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" -msgstr "外部管理的环境" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:72 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +msgid "pyproject type" +msgstr "pyproject.toml" + +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -#, fuzzy -#| msgid "distlib" -msgid "distro" -msgstr "distlib" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "packaging" -msgid "package" -msgstr "打包" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" +msgstr "例子" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:130 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +msgid "Reference Implementation" +msgstr "文档类型" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -msgid "Python-specific package manager" -msgstr "Python 软件包管理器" - -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 +#: ../source/specifications/inline-script-metadata.rst:208 msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 +#: ../source/specifications/inline-script-metadata.rst:231 #, fuzzy -#| msgid "macOS installers and package managers" -msgid "distro package manager" -msgstr "macOS 安装程序和软件包管理器" +msgid "Recommendations" +msgstr "创建文档" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" +msgstr "包名规范化" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." -msgstr "" +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +msgid "Normalization" +msgstr "规范化" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/name-normalization.rst:22 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 -msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 -msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 -msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 -msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 +#: ../source/specifications/name-normalization.rst:44 msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 -msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 -msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 -msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" +msgstr "python 标签" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -#, fuzzy -#| msgid "Runtime detection of virtual environments" -msgid "Guide users towards virtual environments" -msgstr "虚拟环境的 Runtime 检测" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" +msgstr "使用方法" + +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" +msgstr "Python 标签" + +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 -msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" +msgstr "cp: CPython" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" +msgstr "ip: IronPython" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 -msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" +msgstr "jy: Jython" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:66 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 +#: ../source/specifications/platform-compatibility-tags.rst:73 msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 +#: ../source/specifications/platform-compatibility-tags.rst:79 msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "文档类型" - -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" -msgstr "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" -msgstr "``pip install --prefix=/some/path``" - -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" -msgstr "``pip install --user``" - -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 -msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." -msgstr "" +#: ../source/specifications/platform-compatibility-tags.rst:107 +msgid "``manylinux``" +msgstr "``manylinux``" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:110 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 +#: ../source/specifications/platform-compatibility-tags.rst:119 msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." -msgstr "" - -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." -msgstr "" - -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:124 +msgid "" +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 -msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 -msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 -msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "pyproject.toml" -msgid "pyproject type" -msgstr "pyproject.toml" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" -msgstr "例子" - -#: ../source/specifications/inline-script-metadata.rst:110 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "文档类型" - -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 -msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 -msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 -msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -#, fuzzy -#| msgid "Creating Documentation" -msgid "Recommendations" -msgstr "创建文档" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" -msgstr "包名规范化" +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" +msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -msgid "Normalization" -msgstr "规范化" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:261 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:264 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" -msgstr "python 标签" - -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:303 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" -msgstr "使用方法" - -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/platform-compatibility-tags.rst:300 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" -msgstr "Python 标签" - -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" -msgstr "cp: CPython" +#: ../source/specifications/pypirc.rst:32 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" -msgstr "ip: IronPython" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" -msgstr "jy: Jython" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 +#: ../source/specifications/pypirc.rst:43 msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:47 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 -msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:61 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:65 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:81 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:87 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:96 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pypirc.rst:104 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -msgid "``manylinux``" -msgstr "``manylinux``" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "``pyproject.toml`` 规格" -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:10 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:65 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:115 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" +msgstr "``authors``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" -msgstr "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" +msgstr "``dependencies``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" +msgstr "``entry-points``" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +msgid "``maintainers``" +msgstr "``maintainers``" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" -msgstr "``>=3.0.0``" - -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" -msgstr "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +#: ../source/specifications/pyproject-toml.rst:346 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:356 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:359 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:32 -msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:387 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:396 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:398 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:409 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:411 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:96 -msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:427 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:444 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 +#: ../source/specifications/recording-installed-packages.rst:7 msgid "Recording installed projects" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:7 +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -16188,7 +15984,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -16197,11 +15993,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -16212,21 +16008,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -16238,7 +16034,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -16249,7 +16045,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -16261,41 +16057,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -16303,7 +16099,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -16311,58 +16107,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -16370,7 +16166,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -16378,13 +16174,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -16393,7 +16189,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -16402,18 +16198,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -16421,7 +16217,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -16431,11 +16227,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -16443,15 +16239,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -16459,11 +16255,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -16471,29 +16267,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -16502,11 +16298,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -16514,14 +16310,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -16530,7 +16326,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -16547,7 +16343,6 @@ msgstr "" #: ../source/specifications/section-installation-metadata.rst:3 #, fuzzy -#| msgid "Installation format" msgid "Package Installation Metadata" msgstr "安装格式" @@ -16666,10 +16461,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16688,7 +16483,6 @@ msgstr "" #: ../source/specifications/source-distribution-format.rst:76 #, fuzzy -#| msgid "Source Distribution (or \"sdist\")" msgid "Source distribution archive features" msgstr "源代码分发（或“sdist”）" @@ -16841,24 +16635,23 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy -#| msgid "Specifications" msgid "Definitions" msgstr "规格" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16866,7 +16659,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16874,19 +16667,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16894,26 +16687,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy -#| msgid "Versions" msgid "Version scheme" msgstr "版本" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16921,28 +16713,27 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 #, fuzzy -#| msgid "Local version identifiers" msgid "Public version identifiers" msgstr "本地版本标识符" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16950,7 +16741,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16958,63 +16749,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -17022,11 +16813,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -17035,7 +16826,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -17045,7 +16836,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -17054,7 +16845,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -17062,25 +16853,24 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 #, fuzzy -#| msgid "Start & end with an ASCII letter or digit." msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "以一个 ASCII 字母或数字开始和结束。" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -17094,7 +16884,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -17102,7 +16892,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -17114,36 +16904,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -17151,21 +16941,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -17173,37 +16967,36 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 #, fuzzy -#| msgid "zest.releaser" msgid "Pre-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -17211,50 +17004,49 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 #, fuzzy -#| msgid "zest.releaser" msgid "Post-releases" msgstr "zest.releaser" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -17262,7 +17054,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -17270,11 +17062,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -17282,11 +17074,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -17294,20 +17086,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -17316,13 +17108,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -17332,30 +17124,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy -#| msgid "Versions" msgid "Version epochs" msgstr "版本" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -17366,14 +17157,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -17381,24 +17172,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy -#| msgid "Normalization" msgid "Integer Normalization" msgstr "规范化" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -17407,11 +17197,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -17421,11 +17211,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -17435,11 +17225,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -17447,11 +17237,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -17462,11 +17252,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -17474,11 +17264,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -17486,11 +17276,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -17500,11 +17290,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -17512,11 +17302,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -17524,13 +17314,12 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 #, fuzzy -#| msgid "Local version identifiers" msgid "Local version segments" msgstr "本地版本标识符" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -17538,11 +17327,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -17551,11 +17340,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -17564,11 +17353,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -17578,7 +17367,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -17586,69 +17375,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -17656,48 +17445,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -17708,7 +17497,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -17718,17 +17507,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17737,18 +17526,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17759,7 +17548,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17767,30 +17556,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17798,30 +17587,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17829,60 +17618,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17891,81 +17680,80 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 #, fuzzy -#| msgid "Version" msgid "Version matching" msgstr "版本" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17974,7 +17762,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17982,31 +17770,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -18014,7 +17802,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -18023,7 +17811,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -18033,14 +17821,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -18049,30 +17837,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy -#| msgid "Version Specifier" msgid "Version exclusion" msgstr "版本说明符 (Version Specifier)" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -18081,27 +17868,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -18111,7 +17898,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -18121,13 +17908,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -18348,7 +18134,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -18356,7 +18142,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -18367,15 +18153,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "远程 URL 示例::" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -18383,7 +18169,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -18391,7 +18177,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -18403,43 +18189,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -18448,20 +18234,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -18561,7 +18347,6 @@ msgstr "" #: ../source/tutorials/creating-documentation.rst:4 #, fuzzy -#| msgid "Creating Documentation" msgid "Creating documentation" msgstr "创建文档" @@ -19773,28 +19558,32 @@ msgid "" "are some things you can do:" msgstr "" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "阅读关于 :doc:`/guides/packaging-binary-extensions` 。" +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "这是你的项目名称，这决定了你的项目如何在 :term:`PyPI ` 中列出。 根据 :pep:`508`，有效的项目名称必须是：" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "以一个 ASCII 字母或数字开始和结束。" + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "这是你的项目的当前版本，允许你的用户确定他们是否有最新的版本，并指出他们对" +#~ "自己的软件进行过哪些具体的测试。" + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "如果你发布了你的项目，每个版本都会显示在 :term:`PyPI `上。" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "为你的项目提供一个简短和长的描述。" + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "如果你发布你的项目，这些值将显示在 :term:`PyPI `。在``pypi.org``上，用户界面会在灰色横幅上显示``description``，在" +#~ "名为 \"项目描述 \" 的部分显示 ``long_description``。" + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description``也会显示在项目列表中。例如，它在搜索结果页面（如 https://" +#~ "pypi.org/search/?q=jupyter）、热门项目和新版本的头版列表，以及你在账户资料" +#~ "中维护的项目列表（如 https://pypi.org/user/jaraco/）中可见。" + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "为你的项目提供一个主页 URL 。" + +#, fuzzy +#~ msgid "``author``" +#~ msgstr "作者 (author)" + +#~ msgid "Provide details about the author." +#~ msgstr "提供关于作者的详细信息。" + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "提供对你的项目进行分类的分类器列表。有关完整列表，请参阅 https://pypi.org/" +#~ "classifiers/ 。" + +#~ msgid "List keywords that describe your project." +#~ msgstr "列出描述你的项目的关键词。" + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "project_urls" + +#~ msgid "And so on." +#~ msgstr "以此类推。" + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "最常用的入口点是 \"console_scripts\"（见下文）。" + +#~ msgid "Comparison to .egg" +#~ msgstr "与 .egg 的比较" + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "要了解 pipx 的更多信息，可以访问 https://pypa.github.io/pipx/。" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`文档< `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "阅读关于 :doc:`/guides/packaging-binary-extensions` 。" + #, fuzzy -#~| msgid "Creating Documentation" #~ msgid "Current recommendation" #~ msgstr "创建文档" diff --git a/locales/zh_Hant/LC_MESSAGES/messages.po b/locales/zh_Hant/LC_MESSAGES/messages.po index 6fc9d3350..ed0161f39 100644 --- a/locales/zh_Hant/LC_MESSAGES/messages.po +++ b/locales/zh_Hant/LC_MESSAGES/messages.po @@ -10,7 +10,7 @@ msgid "" msgstr "" "Project-Id-Version: Python Packaging User Guide\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-12-01 22:15+0000\n" +"POT-Creation-Date: 2023-12-21 17:40+0000\n" "PO-Revision-Date: 2022-07-30 20:04+0000\n" "Last-Translator: meowmeowmeowcat \n" "Language-Team: Chinese (Traditional) `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "然後載入那個套件:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name (the :ref:" +"`exact rules ` are found in the Python documentation) " +"[#non-identifier-mod-name]_. In particular, they use underscores ``_`` as " +"word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in the :ref:" +"`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + #: ../source/discussions/index.rst:4 msgid "" "**Discussions** are focused on providing comprehensive information about a " @@ -918,7 +1057,7 @@ msgid "" "Python projects. And :file:`setup.py` is a valid configuration file for :ref:" "`setuptools` that happens to be written in Python, instead of in *TOML* for " "example (a similar practice is used by other tools like *nox* and its :file:" -"`nox.py` configuration file, or *pytest* and :file:`conftest.py`)." +"`noxfile.py` configuration file, or *pytest* and :file:`conftest.py`)." msgstr "" #: ../source/discussions/setup-py-deprecated.rst:18 @@ -1059,151 +1198,160 @@ msgid "A trusted replacement is :ref:`twine`:" msgstr "" #: ../source/discussions/setup-py-deprecated.rst:103 -msgid "``python -m twine check``" -msgstr "" +#, fuzzy +msgid "``python -m twine check --strict dist/*``" +msgstr "Python 版本" #: ../source/discussions/setup-py-deprecated.rst:104 #, fuzzy -msgid "``python -m twine register``" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" msgstr "Python 版本" #: ../source/discussions/setup-py-deprecated.rst:105 -msgid "``python -m twine upload``" +#, fuzzy +msgid "``python -m twine upload dist/*``" +msgstr "Python 版本" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:109 +#: ../source/discussions/setup-py-deprecated.rst:112 #, fuzzy msgid "``python setup.py --version``" msgstr "Python 版本" -#: ../source/discussions/setup-py-deprecated.rst:111 +#: ../source/discussions/setup-py-deprecated.rst:114 msgid "" "A possible replacement solution (among others) is to rely on setuptools-scm_:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:113 +#: ../source/discussions/setup-py-deprecated.rst:116 #, fuzzy -msgid "``python -m setuptools-scm``" +msgid "``python -m setuptools_scm``" msgstr "Python 版本" -#: ../source/discussions/setup-py-deprecated.rst:119 +#: ../source/discussions/setup-py-deprecated.rst:122 msgid "Remaining commands" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:121 +#: ../source/discussions/setup-py-deprecated.rst:124 msgid "" "This guide does not make suggestions of replacement solutions for those " "commands:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:126 +#: ../source/discussions/setup-py-deprecated.rst:129 msgid "``alias``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:127 +#: ../source/discussions/setup-py-deprecated.rst:130 msgid "``bdist``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:128 +#: ../source/discussions/setup-py-deprecated.rst:131 msgid "``bdist_dumb``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:129 +#: ../source/discussions/setup-py-deprecated.rst:132 msgid "``bdist_egg``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:130 +#: ../source/discussions/setup-py-deprecated.rst:133 msgid "``bdist_rpm``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:131 +#: ../source/discussions/setup-py-deprecated.rst:134 msgid "``build``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:132 +#: ../source/discussions/setup-py-deprecated.rst:135 msgid "``build_clib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:133 +#: ../source/discussions/setup-py-deprecated.rst:136 msgid "``build_ext``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:134 +#: ../source/discussions/setup-py-deprecated.rst:137 msgid "``build_py``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:135 +#: ../source/discussions/setup-py-deprecated.rst:138 msgid "``build_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:136 +#: ../source/discussions/setup-py-deprecated.rst:139 msgid "``clean``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:137 +#: ../source/discussions/setup-py-deprecated.rst:140 msgid "``dist_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:138 +#: ../source/discussions/setup-py-deprecated.rst:141 #, fuzzy #| msgid "**easy_install**" msgid "``easy_install``" msgstr "**easy_install**" -#: ../source/discussions/setup-py-deprecated.rst:139 +#: ../source/discussions/setup-py-deprecated.rst:142 msgid "``editable_wheel``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:140 +#: ../source/discussions/setup-py-deprecated.rst:143 msgid "``egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:141 +#: ../source/discussions/setup-py-deprecated.rst:144 msgid "``install``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:142 +#: ../source/discussions/setup-py-deprecated.rst:145 msgid "``install_data``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:143 +#: ../source/discussions/setup-py-deprecated.rst:146 msgid "``install_egg_info``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:144 +#: ../source/discussions/setup-py-deprecated.rst:147 #, fuzzy msgid "``install_headers``" msgstr "維護者" -#: ../source/discussions/setup-py-deprecated.rst:145 +#: ../source/discussions/setup-py-deprecated.rst:148 msgid "``install_lib``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:146 +#: ../source/discussions/setup-py-deprecated.rst:149 msgid "``install_scripts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:147 +#: ../source/discussions/setup-py-deprecated.rst:150 msgid "``rotate``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:148 +#: ../source/discussions/setup-py-deprecated.rst:151 msgid "``saveopts``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:149 +#: ../source/discussions/setup-py-deprecated.rst:152 msgid "``setopt``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:150 +#: ../source/discussions/setup-py-deprecated.rst:153 msgid "``upload_docs``" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:154 +#: ../source/discussions/setup-py-deprecated.rst:157 msgid "What about custom commands?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:156 +#: ../source/discussions/setup-py-deprecated.rst:159 msgid "" "Likewise, custom :file:`setup.py` commands are deprecated. The " "recommendation is to migrate those custom commands to a task runner tool or " @@ -1211,46 +1359,46 @@ msgid "" "tox, pydoit, pyinvoke, taskipy, and thx." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:164 +#: ../source/discussions/setup-py-deprecated.rst:167 msgid "What about custom build steps?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:166 +#: ../source/discussions/setup-py-deprecated.rst:169 msgid "" "Custom build steps that for example either overwrite existing steps such as " "``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " "not deprecated. Those will be automatically called as expected." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:173 +#: ../source/discussions/setup-py-deprecated.rst:176 #: ../source/guides/modernize-setup-py-project.rst:21 msgid "Should ``setup.py`` be deleted?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/discussions/setup-py-deprecated.rst:178 msgid "" "Although the usage of :file:`setup.py` as an executable script is " "deprecated, its usage as a configuration file for setuptools is absolutely " "fine. There is likely no modification needed in :file:`setup.py`." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:181 +#: ../source/discussions/setup-py-deprecated.rst:184 msgid "Is ``pyproject.toml`` mandatory?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:183 +#: ../source/discussions/setup-py-deprecated.rst:186 msgid "" "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " "for a project to have a :file:`pyproject.toml` file at the root of its " "source tree with a content like this:" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:194 +#: ../source/discussions/setup-py-deprecated.rst:197 msgid "" "The guide :ref:`modernize-setup-py-project` has more details about this." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:196 +#: ../source/discussions/setup-py-deprecated.rst:199 msgid "" "The standard fallback behavior for a :term:`build frontend ` " "in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " @@ -1258,26 +1406,26 @@ msgid "" "setuptools." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:202 +#: ../source/discussions/setup-py-deprecated.rst:205 msgid "Why? What does it all mean?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:204 +#: ../source/discussions/setup-py-deprecated.rst:207 msgid "" "One way to look at it is that the scope of setuptools has now been reduced " "to the role of a build backend." msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:209 +#: ../source/discussions/setup-py-deprecated.rst:212 #: ../source/guides/modernize-setup-py-project.rst:244 msgid "Where to read more about this?" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/discussions/setup-py-deprecated.rst:214 msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" msgstr "" -#: ../source/discussions/setup-py-deprecated.rst:213 +#: ../source/discussions/setup-py-deprecated.rst:216 msgid ":doc:`setuptools:deprecated/commands`" msgstr "" @@ -1594,24 +1742,28 @@ msgstr "" #: ../source/flow.rst:97 msgid "" "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); see :" -"doc:`Declaring project metadata ` for more detail" +"specifications/core-metadata/>` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." msgstr "" #: ../source/flow.rst:103 -msgid "a ``[tool]`` table containing tool-specific configuration options" +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." msgstr "" -#: ../source/flow.rst:106 +#: ../source/flow.rst:108 msgid "Build artifacts" msgstr "" -#: ../source/flow.rst:109 +#: ../source/flow.rst:111 msgid "The source distribution (sdist)" msgstr "" -#: ../source/flow.rst:111 +#: ../source/flow.rst:113 msgid "" "A source distribution contains enough to install the package from source in " "an end user's Python environment. As such, it needs the package source, and " @@ -1620,22 +1772,22 @@ msgid "" "compilation step is required (such as a C extension)." msgstr "" -#: ../source/flow.rst:117 ../source/flow.rst:141 +#: ../source/flow.rst:119 ../source/flow.rst:143 msgid "" "The :ref:`build` package knows how to invoke your build tool to create one " "of these:" msgstr "" -#: ../source/flow.rst:124 +#: ../source/flow.rst:126 msgid "" "Or, your build tool may provide its own interface for creating an sdist." msgstr "" -#: ../source/flow.rst:128 +#: ../source/flow.rst:130 msgid "The built distributions (wheels)" msgstr "" -#: ../source/flow.rst:130 +#: ../source/flow.rst:132 msgid "" "A built distribution contains only the files needed for an end user's Python " "environment. No compilation steps are required during the install, and the " @@ -1643,7 +1795,7 @@ msgid "" "makes the install faster and more convenient for end users." msgstr "" -#: ../source/flow.rst:135 +#: ../source/flow.rst:137 msgid "" "A pure Python package typically needs only one \"generic\" wheel. A package " "with compiled binary extensions needs a wheel for each supported combination " @@ -1652,43 +1804,43 @@ msgid "" "will fall back to installing the source distribution." msgstr "" -#: ../source/flow.rst:148 +#: ../source/flow.rst:150 msgid "Or, your build tool may provide its own interface for creating a wheel." msgstr "" -#: ../source/flow.rst:152 +#: ../source/flow.rst:154 msgid "" "The default behaviour of :ref:`build` is to make both an sdist and a wheel " "from the source in the current directory; the above examples are " "deliberately specific." msgstr "" -#: ../source/flow.rst:157 +#: ../source/flow.rst:159 msgid "Upload to the package distribution service" msgstr "" -#: ../source/flow.rst:159 +#: ../source/flow.rst:161 msgid "" "The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " "using a command like:" msgstr "" -#: ../source/flow.rst:166 +#: ../source/flow.rst:168 msgid "Or, your build tool may provide its own interface for uploading." msgstr "" -#: ../source/flow.rst:169 +#: ../source/flow.rst:171 msgid "Download and install" msgstr "" -#: ../source/flow.rst:171 +#: ../source/flow.rst:173 msgid "" "Now that the package is published, end users can download and install the " "package into their Python environment. Typically this is done with :ref:" "`pip`, using a command like:" msgstr "" -#: ../source/flow.rst:179 +#: ../source/flow.rst:181 msgid "" "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :" "ref:`pdm`." @@ -1779,14 +1931,15 @@ msgid "" "Package` (which is also commonly called a \"package\") or another kind of " "distribution (e.g. a Linux distribution or the Python language " "distribution), which are often referred to with the single term " -"\"distribution\"." +"\"distribution\". See :ref:`distribution-package-vs-import-package` for a " +"breakdown of the differences." msgstr "" -#: ../source/glossary.rst:71 +#: ../source/glossary.rst:72 msgid "Egg" msgstr "" -#: ../source/glossary.rst:74 +#: ../source/glossary.rst:75 msgid "" "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " "is being replaced by :term:`Wheel`. For details, see :doc:`The Internal " @@ -1794,11 +1947,11 @@ msgid "" "Eggs `_" msgstr "" -#: ../source/glossary.rst:78 +#: ../source/glossary.rst:79 msgid "Extension Module" msgstr "" -#: ../source/glossary.rst:81 +#: ../source/glossary.rst:82 msgid "" "A :term:`Module` written in the low-level language of the Python " "implementation: C/C++ for Python, Java for Jython. Typically contained in a " @@ -1807,11 +1960,11 @@ msgid "" "Python extensions on Windows, or a Java class file for Jython extensions." msgstr "" -#: ../source/glossary.rst:88 +#: ../source/glossary.rst:89 msgid "Known Good Set (KGS)" msgstr "" -#: ../source/glossary.rst:91 +#: ../source/glossary.rst:92 msgid "" "A set of distributions at specified versions which are compatible with each " "other. Typically a test suite will be run which passes all tests before a " @@ -1820,67 +1973,68 @@ msgid "" "distributions." msgstr "" -#: ../source/glossary.rst:97 +#: ../source/glossary.rst:98 msgid "Import Package" msgstr "" -#: ../source/glossary.rst:100 +#: ../source/glossary.rst:101 msgid "" "A Python module which can contain other modules or recursively, other " "packages." msgstr "" -#: ../source/glossary.rst:103 +#: ../source/glossary.rst:104 msgid "" "An import package is more commonly referred to with the single word " "\"package\", but this guide will use the expanded term when more clarity is " "needed to prevent confusion with a :term:`Distribution Package` which is " -"also commonly called a \"package\"." +"also commonly called a \"package\". See :ref:`distribution-package-vs-import-" +"package` for a breakdown of the differences." msgstr "" -#: ../source/glossary.rst:107 +#: ../source/glossary.rst:109 msgid "Module" msgstr "" -#: ../source/glossary.rst:110 +#: ../source/glossary.rst:112 msgid "" "The basic unit of code reusability in Python, existing in one of two types: :" "term:`Pure Module`, or :term:`Extension Module`." msgstr "" -#: ../source/glossary.rst:113 +#: ../source/glossary.rst:115 msgid "Package Index" msgstr "套件索引" -#: ../source/glossary.rst:116 +#: ../source/glossary.rst:118 msgid "" "A repository of distributions with a web interface to automate :term:" "`package ` discovery and consumption." msgstr "" -#: ../source/glossary.rst:119 +#: ../source/glossary.rst:121 msgid "Per Project Index" msgstr "" -#: ../source/glossary.rst:122 +#: ../source/glossary.rst:124 msgid "" "A private or other non-canonical :term:`Package Index` indicated by a " "specific :term:`Project` as the index preferred or required to resolve " "dependencies of that project." msgstr "" -#: ../source/glossary.rst:126 +#: ../source/glossary.rst:128 msgid "Project" msgstr "" -#: ../source/glossary.rst:129 +#: ../source/glossary.rst:131 msgid "" "A library, framework, script, plugin, application, or collection of data or " "other resources, or some combination thereof that is intended to be packaged " "into a :term:`Distribution `." msgstr "" -#: ../source/glossary.rst:133 +#: ../source/glossary.rst:135 msgid "" "Since most projects create :term:`Distributions ` " "using either :pep:`518` ``build-system``, :ref:`distutils` or :ref:" @@ -1889,7 +2043,7 @@ msgid "" "`setup.cfg` file at the root of the project source directory." msgstr "" -#: ../source/glossary.rst:139 +#: ../source/glossary.rst:141 msgid "" "Python projects must have unique names, which are registered on :term:`PyPI " "`. Each project will then contain one or more :" @@ -1897,7 +2051,7 @@ msgid "" "`distributions `." msgstr "" -#: ../source/glossary.rst:144 +#: ../source/glossary.rst:146 msgid "" "Note that there is a strong convention to name a project after the name of " "the package that is imported to run that project. However, this doesn't have " @@ -1905,21 +2059,21 @@ msgid "" "and have it provide a package importable only as 'bar'." msgstr "" -#: ../source/glossary.rst:150 +#: ../source/glossary.rst:152 msgid "Pure Module" msgstr "" -#: ../source/glossary.rst:153 +#: ../source/glossary.rst:155 msgid "" "A :term:`Module` written in Python and contained in a single ``.py`` file " "(and possibly associated ``.pyc`` and/or ``.pyo`` files)." msgstr "" -#: ../source/glossary.rst:156 +#: ../source/glossary.rst:158 msgid "Python Packaging Authority (PyPA)" msgstr "" -#: ../source/glossary.rst:159 +#: ../source/glossary.rst:161 msgid "" "PyPA is a working group that maintains many of the relevant projects in " "Python packaging. They maintain a site at :doc:`pypa.io `, host " @@ -1929,48 +2083,48 @@ msgid "" "`the Python Discourse forum `__." msgstr "" -#: ../source/glossary.rst:168 +#: ../source/glossary.rst:170 msgid "Python Package Index (PyPI)" msgstr "" -#: ../source/glossary.rst:171 +#: ../source/glossary.rst:173 msgid "" "`PyPI `_ is the default :term:`Package Index` for the " "Python community. It is open to all Python developers to consume and " "distribute their distributions." msgstr "" -#: ../source/glossary.rst:174 +#: ../source/glossary.rst:176 msgid "pypi.org" msgstr "" -#: ../source/glossary.rst:177 +#: ../source/glossary.rst:179 msgid "" "`pypi.org `_ is the domain name for the :term:`Python " "Package Index (PyPI)`. It replaced the legacy index domain name, ``pypi." "python.org``, in 2017. It is powered by :ref:`warehouse`." msgstr "" -#: ../source/glossary.rst:181 +#: ../source/glossary.rst:183 msgid "pyproject.toml" msgstr "" -#: ../source/glossary.rst:184 +#: ../source/glossary.rst:186 msgid "" "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." msgstr "" -#: ../source/glossary.rst:186 +#: ../source/glossary.rst:188 msgid "Release" msgstr "" -#: ../source/glossary.rst:189 +#: ../source/glossary.rst:191 msgid "" "A snapshot of a :term:`Project` at a particular point in time, denoted by a " "version identifier." msgstr "" -#: ../source/glossary.rst:192 +#: ../source/glossary.rst:194 msgid "" "Making a release may entail the publishing of multiple :term:`Distributions " "`. For example, if version 1.0 of a project was " @@ -1978,11 +2132,11 @@ msgid "" "Windows installer distribution format." msgstr "" -#: ../source/glossary.rst:197 +#: ../source/glossary.rst:199 msgid "Requirement" msgstr "" -#: ../source/glossary.rst:200 +#: ../source/glossary.rst:202 msgid "" "A specification for a :term:`package ` to be " "installed. :ref:`pip`, the :term:`PYPA ` " @@ -1991,17 +2145,15 @@ msgid "" "install` reference." msgstr "" -#: ../source/glossary.rst:206 +#: ../source/glossary.rst:208 msgid "Requirement Specifier" msgstr "" -#: ../source/glossary.rst:209 +#: ../source/glossary.rst:211 msgid "" "A format used by :ref:`pip` to install packages from a :term:`Package " -"Index`. For an EBNF diagram of the format, see the `pkg_resources." -"Requirement `_ entry in the :ref:`setuptools` docs. For " -"example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " +"Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`. " +"For example, \"foo>=1.3\" is a requirement specifier, where \"foo\" is the " "project name, and the \">=1.3\" portion is the :term:`Version Specifier`" msgstr "" @@ -2017,12 +2169,12 @@ msgid "" msgstr "" #: ../source/glossary.rst:223 -#: ../source/guides/distributing-packages-using-setuptools.rst:56 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 msgid "setup.py" msgstr "" #: ../source/glossary.rst:224 -#: ../source/guides/distributing-packages-using-setuptools.rst:77 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 msgid "setup.cfg" msgstr "" @@ -2181,7 +2333,7 @@ msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:35 msgid "" -"In short, because it's value is low for various reasons, and the tradeoffs " +"In short, because its value is low for various reasons, and the tradeoffs " "required to make it work are high, it has been not an effective use of " "limited resources." msgstr "" @@ -2250,14 +2402,14 @@ msgid "Column" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/core-metadata.rst:196 +#: ../source/specifications/core-metadata.rst:198 msgid "Description" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:75 -#: ../source/specifications/dependency-specifiers.rst:27 -#: ../source/specifications/direct-url-data-structure.rst:234 -#: ../source/specifications/version-specifiers.rst:1063 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:217 +#: ../source/specifications/version-specifiers.rst:1065 msgid "Examples" msgstr "" @@ -2613,8 +2765,7 @@ msgid "" msgstr "" #: ../source/guides/analyzing-pypi-package-downloads.rst:335 -#: ../source/specifications/binary-distribution-format.rst:482 -#: ../source/specifications/dependency-specifiers.rst:483 +#: ../source/specifications/dependency-specifiers.rst:489 msgid "References" msgstr "" @@ -2789,6 +2940,16 @@ msgid "Packaging and distributing projects" msgstr "" #: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2017-12-01" +msgid "2023-12-14" +msgstr "2017-12-01" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 msgid "" "This section covers some additional details on configuring, packaging and " "distributing Python projects with ``setuptools`` that aren't covered by the " @@ -2797,14 +2958,14 @@ msgid "" "tutorials/installing-packages` page." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:13 +#: ../source/guides/distributing-packages-using-setuptools.rst:16 msgid "" "The section does *not* aim to cover best practices for Python project " "development as a whole. For example, it does not provide guidance or tool " "recommendations for version control, documentation, or testing." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:17 +#: ../source/guides/distributing-packages-using-setuptools.rst:20 msgid "" "For more reference material, see :std:doc:`Building and Distributing " "Packages ` in the :ref:`setuptools` docs, but " @@ -2812,36 +2973,36 @@ msgid "" "conflicts, prefer the advice in the Python Packaging User Guide." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:25 +#: ../source/guides/distributing-packages-using-setuptools.rst:28 msgid "Requirements for packaging and distributing" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:26 +#: ../source/guides/distributing-packages-using-setuptools.rst:29 msgid "" "First, make sure you have already fulfilled the :ref:`requirements for " "installing packages `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:29 +#: ../source/guides/distributing-packages-using-setuptools.rst:32 msgid "Install \"twine\" [1]_:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:43 +#: ../source/guides/distributing-packages-using-setuptools.rst:46 msgid "" "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " "`)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:49 +#: ../source/guides/distributing-packages-using-setuptools.rst:52 msgid "Configuring your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:53 +#: ../source/guides/distributing-packages-using-setuptools.rst:56 msgid "Initial files" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:58 +#: ../source/guides/distributing-packages-using-setuptools.rst:61 msgid "" "The most important file is :file:`setup.py` which exists at the root of your " "project directory. For an example, see the `setup.py `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:63 +#: ../source/guides/distributing-packages-using-setuptools.rst:66 msgid ":file:`setup.py` serves two primary functions:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:65 +#: ../source/guides/distributing-packages-using-setuptools.rst:68 msgid "" "It's the file where various aspects of your project are configured. The " "primary feature of :file:`setup.py` is that it contains a global ``setup()`` " @@ -2862,14 +3023,14 @@ msgid "" "ref:`the section below `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:71 +#: ../source/guides/distributing-packages-using-setuptools.rst:74 msgid "" "It's the command line interface for running various commands that relate to " "packaging tasks. To get a listing of available commands, run ``python3 setup." "py --help-commands``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:79 +#: ../source/guides/distributing-packages-using-setuptools.rst:82 msgid "" ":file:`setup.cfg` is an ini file that contains option defaults for :file:" "`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:86 +#: ../source/guides/distributing-packages-using-setuptools.rst:89 msgid "README.rst / README.md" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:88 +#: ../source/guides/distributing-packages-using-setuptools.rst:91 msgid "" "All projects should contain a readme file that covers the goal of the " "project. The most common format is `reStructuredText ` argument)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:95 +#: ../source/guides/distributing-packages-using-setuptools.rst:98 msgid "" "For an example, see `README.md `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:99 +#: ../source/guides/distributing-packages-using-setuptools.rst:102 msgid "" "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:" "`README.rst`, :file:`README.txt`, or :file:`README`) included in source " @@ -2909,11 +3070,11 @@ msgid "" "include it to be explicit." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:108 +#: ../source/guides/distributing-packages-using-setuptools.rst:111 msgid "MANIFEST.in" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:113 msgid "" "A :file:`MANIFEST.in` is needed when you need to package additional files " "that are not automatically included in a source distribution. For details " @@ -2921,7 +3082,7 @@ msgid "" "by default, see \":ref:`Using MANIFEST.in`\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:115 +#: ../source/guides/distributing-packages-using-setuptools.rst:118 msgid "" "However, you may not have to use a :file:`MANIFEST.in`. For an example, the " "`PyPA sample project `_ has removed " @@ -2929,16 +3090,16 @@ msgid "" "`setuptools` 43.0.0 and newer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:120 +#: ../source/guides/distributing-packages-using-setuptools.rst:123 msgid "" ":file:`MANIFEST.in` does not affect binary distributions such as wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:123 +#: ../source/guides/distributing-packages-using-setuptools.rst:126 msgid "LICENSE.txt" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:125 +#: ../source/guides/distributing-packages-using-setuptools.rst:128 msgid "" "Every package should include a license file detailing the terms of " "distribution. In many jurisdictions, packages without an explicit license " @@ -2948,257 +3109,68 @@ msgid "" "lawyer." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:131 +#: ../source/guides/distributing-packages-using-setuptools.rst:134 msgid "" "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:136 +#: ../source/guides/distributing-packages-using-setuptools.rst:139 msgid "" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:138 +#: ../source/guides/distributing-packages-using-setuptools.rst:141 msgid "" "Although it's not required, the most common practice is to include your " "Python modules and packages under a single top-level package that has the " "same :ref:`name ` as your project, or something very close." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:142 +#: ../source/guides/distributing-packages-using-setuptools.rst:145 msgid "" "For an example, see the `sample `_ package that's included in the `PyPA sample project " "`_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:150 +#: ../source/guides/distributing-packages-using-setuptools.rst:153 msgid "setup() args" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:152 +#: ../source/guides/distributing-packages-using-setuptools.rst:155 msgid "" "As mentioned above, the primary feature of :file:`setup.py` is that it " "contains a global ``setup()`` function. The keyword arguments to this " "function are how specific details of your project are defined." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:156 -msgid "" -"The most relevant arguments are explained below. Most of the snippets given " -"are taken from the `setup.py `_ contained in the `PyPA " -"sample project `_." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:165 -#: ../source/guides/writing-pyproject-toml.rst:120 -#: ../source/specifications/declaring-project-metadata.rst:41 -#: ../source/specifications/declaring-project-metadata.rst:63 -#: ../source/specifications/declaring-project-metadata.rst:73 -msgid "``name``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:171 -msgid "" -"This is the name of your project, determining how your project is listed on :" -"term:`PyPI `. Per :pep:`508`, valid project " -"names must:" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:175 -msgid "" -"Consist only of ASCII letters, digits, underscores (``_``), hyphens (``-``), " -"and/or periods (``.``), and" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:177 -msgid "Start & end with an ASCII letter or digit." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:179 -msgid "" -"Comparison of project names is case insensitive and treats arbitrarily-long " -"runs of underscores, hyphens, and/or periods as equal. For example, if you " -"register a project named ``cool-stuff``, users will be able to download it " -"or declare a dependency on it using any of the following spellings::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:191 -#: ../source/guides/writing-pyproject-toml.rst:132 -#: ../source/specifications/declaring-project-metadata.rst:46 -#: ../source/specifications/declaring-project-metadata.rst:69 -#: ../source/specifications/declaring-project-metadata.rst:85 -msgid "``version``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:197 +#: ../source/guides/distributing-packages-using-setuptools.rst:159 msgid "" -"This is the current version of your project, allowing your users to " -"determine whether or not they have the latest version, and to indicate which " -"specific versions they've tested their own software against." +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:201 +#: ../source/guides/distributing-packages-using-setuptools.rst:163 msgid "" -"Versions are displayed on :term:`PyPI ` for " -"each release if you publish your project." +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#: ../source/guides/distributing-packages-using-setuptools.rst:170 msgid "" "See :ref:`Choosing a versioning scheme` for more information on ways to use " "versions to convey compatibility information to your users." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:207 -msgid "" -"If the project code itself needs run-time access to the version, the " -"simplest way is to keep the version in both :file:`setup.py` and your code. " -"If you'd rather not duplicate the value, there are a few ways to manage " -"this. See the \":ref:`Single sourcing the version`\" Advanced Topics section." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:215 -#: ../source/guides/writing-pyproject-toml.rst:263 -#: ../source/specifications/declaring-project-metadata.rst:56 -#: ../source/specifications/declaring-project-metadata.rst:98 -msgid "``description``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:223 -msgid "Give a short and long description for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:225 -msgid "" -"These values will be displayed on :term:`PyPI ` " -"if you publish your project. On ``pypi.org``, the user interface displays " -"``description`` in the grey banner and ``long_description`` in the section " -"named \"Project Description\"." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:230 -msgid "" -"``description`` is also displayed in lists of projects. For example, it's " -"visible in the search results pages such as https://pypi.org/search/?" -"q=jupyter, the front-page lists of trending projects and new releases, and " -"the list of projects you maintain within your account profile (such as " -"https://pypi.org/user/jaraco/)." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:236 -msgid "" -"A `content type `_ can be specified with the " -"``long_description_content_type`` argument, which can be one of ``text/" -"plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " -"formatting, `reStructuredText (reST) `_, and the GitHub-flavored " -"Markdown dialect of `Markdown `_ respectively." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:246 -msgid "``url``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:253 -msgid "Give a homepage URL for your project." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:257 -msgid "``author``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:264 -msgid "Provide details about the author." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:268 -#: ../source/guides/writing-pyproject-toml.rst:302 -#: ../source/specifications/declaring-project-metadata.rst:61 -#: ../source/specifications/declaring-project-metadata.rst:157 -msgid "``license``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:274 -msgid "" -"The ``license`` argument doesn't have to indicate the license under which " -"your package is being released, although you may optionally do so if you " -"want. If you're using a standard, well-known license, then your main " -"indication can and should be via the ``classifiers`` argument. Classifiers " -"exist for all major open-source licenses." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:280 -msgid "" -"The ``license`` argument is more typically used to indicate differences from " -"well-known licenses, or to include your own, unique license. As a general " -"rule, it's a good idea to use a standard, well-known license, both to avoid " -"confusion and because some organizations avoid software whose license is " -"unapproved." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:288 -#: ../source/guides/writing-pyproject-toml.rst:335 -#: ../source/specifications/declaring-project-metadata.rst:54 -#: ../source/specifications/declaring-project-metadata.rst:224 -msgid "``classifiers``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:317 -msgid "" -"Provide a list of classifiers that categorize your project. For a full " -"listing, see https://pypi.org/classifiers/." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:320 -msgid "" -"Although the list of classifiers is often used to declare what Python " -"versions a project supports, this information is only used for searching & " -"browsing projects on PyPI, not for installing projects. To actually " -"restrict what Python versions a project can be installed on, use the :ref:" -"`python_requires` argument." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:326 -msgid "" -"To prevent a package from being uploaded to PyPI, use the special " -"``'Private :: Do Not Upload'`` classifier. PyPI will always reject packages " -"with classifiers beginning with ``\"Private ::'``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:332 -#: ../source/guides/writing-pyproject-toml.rst:323 -#: ../source/specifications/declaring-project-metadata.rst:60 -#: ../source/specifications/declaring-project-metadata.rst:214 -msgid "``keywords``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:338 -msgid "List keywords that describe your project." -msgstr "列出描述您的項目的關鍵字。" - -#: ../source/guides/distributing-packages-using-setuptools.rst:342 -#, fuzzy -msgid "``project_urls``" -msgstr "project_urls" - -#: ../source/guides/distributing-packages-using-setuptools.rst:354 -msgid "" -"List additional relevant URLs about your project. This is the place to link " -"to bug trackers, source repositories, or where to support package " -"development. The string of the key is the exact text that will be displayed " -"on PyPI." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:360 +#: ../source/guides/distributing-packages-using-setuptools.rst:177 msgid "``packages``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:183 msgid "" "Set ``packages`` to a list of all :term:`packages ` in your " "project, including their subpackages, sub-subpackages, etc. Although the " @@ -3208,78 +3180,39 @@ msgid "" "not intended to be released and installed." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:375 +#: ../source/guides/distributing-packages-using-setuptools.rst:192 msgid "``py_modules``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:381 +#: ../source/guides/distributing-packages-using-setuptools.rst:198 msgid "" "If your project contains any single-file Python modules that aren't part of " "a package, set ``py_modules`` to a list of the names of the modules (minus " "the ``.py`` extension) in order to make :ref:`setuptools` aware of them." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:387 +#: ../source/guides/distributing-packages-using-setuptools.rst:204 msgid "``install_requires``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:393 +#: ../source/guides/distributing-packages-using-setuptools.rst:210 msgid "" "\"install_requires\" should be used to specify what dependencies a project " "minimally needs to run. When the project is installed by :ref:`pip`, this is " "the specification that is used to install its dependencies." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:397 +#: ../source/guides/distributing-packages-using-setuptools.rst:214 msgid "" "For more on using \"install_requires\" see :ref:`install_requires vs " "Requirements files`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:403 -msgid "``python_requires``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:405 -msgid "" -"If your project only runs on certain Python versions, setting the " -"``python_requires`` argument to the appropriate :pep:`440` version specifier " -"string will prevent :ref:`pip` from installing the project on other Python " -"versions. For example, if your package is for Python 3+ only, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:412 -msgid "" -"If your package is for Python 2.6, 2.7, and all versions of Python 3 " -"starting with 3.3, write::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:417 -msgid "And so on." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:421 -msgid "" -"Support for this feature is relatively recent. Your project's source " -"distributions and wheels (see :ref:`Packaging Your Project`) must be built " -"using at least version 24.2.0 of :ref:`setuptools` in order for the " -"``python_requires`` argument to be recognized and the appropriate metadata " -"generated." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:427 -msgid "" -"In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " -"``python_requires`` metadata. Users with earlier versions of pip will be " -"able to download & install projects on any Python version regardless of the " -"projects' ``python_requires`` values." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:436 +#: ../source/guides/distributing-packages-using-setuptools.rst:221 msgid "``package_data``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:445 +#: ../source/guides/distributing-packages-using-setuptools.rst:230 msgid "" "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " @@ -3288,24 +3221,24 @@ msgid "" "\"package data\"." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:450 +#: ../source/guides/distributing-packages-using-setuptools.rst:235 msgid "" "The value must be a mapping from package name to a list of relative path " "names that should be copied into the package. The paths are interpreted as " "relative to the directory containing the package." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:454 +#: ../source/guides/distributing-packages-using-setuptools.rst:239 msgid "" "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:462 +#: ../source/guides/distributing-packages-using-setuptools.rst:247 msgid "``data_files``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:468 +#: ../source/guides/distributing-packages-using-setuptools.rst:253 msgid "" "Although configuring :ref:`Package Data` is sufficient for most needs, in " "some cases you may need to place data files *outside* of your :term:" @@ -3314,7 +3247,7 @@ msgid "" "other programs, which may be unaware of Python packages." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:474 +#: ../source/guides/distributing-packages-using-setuptools.rst:259 msgid "" "Each ``(directory, files)`` pair in the sequence specifies the installation " "directory and the files to install there. The ``directory`` must be a " @@ -3326,13 +3259,13 @@ msgid "" "of the project source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:484 +#: ../source/guides/distributing-packages-using-setuptools.rst:269 msgid "" "For more information see the distutils section on :ref:`Installing " "Additional Files `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:489 +#: ../source/guides/distributing-packages-using-setuptools.rst:274 msgid "" "When installing packages as egg, ``data_files`` is not supported. So, if " "your project uses :ref:`setuptools`, you must use ``pip`` to install it. " @@ -3340,12 +3273,12 @@ msgid "" "the ``--old-and-unmanageable`` option." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:496 -#: ../source/specifications/declaring-project-metadata.rst:67 +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:146 msgid "``scripts``" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:498 +#: ../source/guides/distributing-packages-using-setuptools.rst:283 msgid "" "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " @@ -3353,69 +3286,28 @@ msgid "" "ref:`console_scripts` entry points (see below)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:505 -msgid "``entry_points``" +#: ../source/guides/distributing-packages-using-setuptools.rst:295 +msgid "Choosing a versioning scheme" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:514 -msgid "" -"Use this keyword to specify any plugins that your project provides for any " -"named entry points that may be defined by your project or others that you " -"depend on." +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Standards compliance for interoperability" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:517 +#: ../source/guides/distributing-packages-using-setuptools.rst:300 msgid "" -"For more information, see the section on :ref:`Advertising Behavior " -"` from the :ref:" -"`setuptools` docs." +"Different Python projects may use different versioning schemes based on the " +"needs of that particular project, but all of them are required to comply " +"with the flexible :pep:`public version scheme <440#public-version-" +"identifiers>` specified in :pep:`440` in order to be supported in tools and " +"libraries like ``pip`` and ``setuptools``." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:521 -msgid "The most commonly used entry point is \"console_scripts\" (see below)." +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "Here are some examples of compliant version numbers::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:526 -msgid "``console_scripts``" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:536 -msgid "" -"Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can then let " -"the toolchain handle the work of turning these interfaces into actual " -"scripts [2]_. The scripts will be generated during the install of your :" -"term:`distribution `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:543 -msgid "" -"For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:549 -msgid "Choosing a versioning scheme" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:552 -msgid "Standards compliance for interoperability" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:554 -msgid "" -"Different Python projects may use different versioning schemes based on the " -"needs of that particular project, but all of them are required to comply " -"with the flexible :pep:`public version scheme <440#public-version-" -"identifiers>` specified in :pep:`440` in order to be supported in tools and " -"libraries like ``pip`` and ``setuptools``." -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:560 -msgid "Here are some examples of compliant version numbers::" -msgstr "" - -#: ../source/guides/distributing-packages-using-setuptools.rst:571 +#: ../source/guides/distributing-packages-using-setuptools.rst:317 msgid "" "To further accommodate historical variations in approaches to version " "numbering, :pep:`440` also defines a comprehensive technique for :pep:" @@ -3423,42 +3315,42 @@ msgid "" "different version numbers to a standardised canonical form." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:577 +#: ../source/guides/distributing-packages-using-setuptools.rst:323 msgid "Scheme choices" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:580 +#: ../source/guides/distributing-packages-using-setuptools.rst:326 msgid "Semantic versioning (preferred)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:582 +#: ../source/guides/distributing-packages-using-setuptools.rst:328 msgid "" "For new projects, the recommended versioning scheme is based on `Semantic " "Versioning `_, but adopts a different approach to " "handling pre-releases and build metadata." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:586 +#: ../source/guides/distributing-packages-using-setuptools.rst:332 msgid "" "The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE " "numbering scheme, where the project author increments:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/guides/distributing-packages-using-setuptools.rst:335 msgid "MAJOR version when they make incompatible API changes," msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:590 +#: ../source/guides/distributing-packages-using-setuptools.rst:336 msgid "" "MINOR version when they add functionality in a backwards-compatible manner, " "and" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:591 +#: ../source/guides/distributing-packages-using-setuptools.rst:337 msgid "MAINTENANCE version when they make backwards-compatible bug fixes." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:593 +#: ../source/guides/distributing-packages-using-setuptools.rst:339 msgid "" "Adopting this approach as a project author allows users to make use of :pep:" "`\"compatible release\" <440#compatible-release>` specifiers, where ``name " @@ -3466,58 +3358,58 @@ msgid "" "with a matching MAJOR version." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:598 +#: ../source/guides/distributing-packages-using-setuptools.rst:344 msgid "" "Python projects adopting semantic versioning should abide by clauses 1-8 of " "the `Semantic Versioning 2.0.0 specification `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:602 +#: ../source/guides/distributing-packages-using-setuptools.rst:348 msgid "Date based versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:604 +#: ../source/guides/distributing-packages-using-setuptools.rst:350 msgid "" "Semantic versioning is not a suitable choice for all projects, such as those " "with a regular time based release cadence and a deprecation process that " "provides warnings for a number of releases prior to removal of a feature." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:608 +#: ../source/guides/distributing-packages-using-setuptools.rst:354 msgid "" "A key advantage of date based versioning is that it is straightforward to " "tell how old the base feature set of a particular release is given just the " "version number." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:611 +#: ../source/guides/distributing-packages-using-setuptools.rst:357 msgid "" "Version numbers for date based projects typically take the form of YEAR." "MONTH (for example, ``12.04``, ``15.10``)." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:615 +#: ../source/guides/distributing-packages-using-setuptools.rst:361 msgid "Serial versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:617 +#: ../source/guides/distributing-packages-using-setuptools.rst:363 msgid "" "This is the simplest possible versioning scheme, and consists of a single " "number which is incremented every release." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:620 +#: ../source/guides/distributing-packages-using-setuptools.rst:366 msgid "" "While serial versioning is very easy to manage as a developer, it is the " "hardest to track as an end user, as serial version numbers convey little or " "no information regarding API backwards compatibility." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:625 +#: ../source/guides/distributing-packages-using-setuptools.rst:371 msgid "Hybrid schemes" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:627 +#: ../source/guides/distributing-packages-using-setuptools.rst:373 msgid "" "Combinations of the above schemes are possible. For example, a project may " "combine date based versioning with serial versioning to create a YEAR.SERIAL " @@ -3525,44 +3417,44 @@ msgid "" "doesn't otherwise commit to a particular release cadence within the year." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:633 +#: ../source/guides/distributing-packages-using-setuptools.rst:379 msgid "Pre-release versioning" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:635 +#: ../source/guides/distributing-packages-using-setuptools.rst:381 msgid "" "Regardless of the base versioning scheme, pre-releases for a given final " "release may be published as:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:638 +#: ../source/guides/distributing-packages-using-setuptools.rst:384 msgid "zero or more dev releases (denoted with a \".devN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:639 +#: ../source/guides/distributing-packages-using-setuptools.rst:385 msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:640 +#: ../source/guides/distributing-packages-using-setuptools.rst:386 msgid "zero or more beta releases (denoted with a \".bN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:641 +#: ../source/guides/distributing-packages-using-setuptools.rst:387 msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:643 +#: ../source/guides/distributing-packages-using-setuptools.rst:389 msgid "" "``pip`` and other modern Python package installers ignore pre-releases by " "default when deciding which versions of dependencies to install." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:648 -#: ../source/specifications/version-specifiers.rst:110 +#: ../source/guides/distributing-packages-using-setuptools.rst:394 +#: ../source/specifications/version-specifiers.rst:112 msgid "Local version identifiers" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:650 +#: ../source/guides/distributing-packages-using-setuptools.rst:396 msgid "" "Public version identifiers are designed to support distribution via :term:" "`PyPI `. Python's software distribution tools " @@ -3572,17 +3464,17 @@ msgid "" "maintained by a redistributor." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:657 +#: ../source/guides/distributing-packages-using-setuptools.rst:403 msgid "" "A local version identifier takes the form ``+``. For example::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:665 +#: ../source/guides/distributing-packages-using-setuptools.rst:411 msgid "Working in \"development mode\"" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:667 +#: ../source/guides/distributing-packages-using-setuptools.rst:413 msgid "" "You can install a project in \"editable\" or \"develop\" mode while you're " "working on it. When installed as editable, a project can be edited in-place " @@ -3591,13 +3483,13 @@ msgid "" "started." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:673 +#: ../source/guides/distributing-packages-using-setuptools.rst:419 msgid "" "To install a Python package in \"editable\"/\"development\" mode Change " "directory to the root of the project directory and run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:681 +#: ../source/guides/distributing-packages-using-setuptools.rst:427 msgid "" "The pip command-line flag ``-e`` is short for ``--editable``, and ``.`` " "refers to the current working directory, so together, it means to install " @@ -3607,7 +3499,7 @@ msgid "" "usual, non-editable mode." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:688 +#: ../source/guides/distributing-packages-using-setuptools.rst:434 msgid "" "You may want to install some of your dependencies in editable mode as well. " "For example, supposing your project requires \"foo\" and \"bar\", but you " @@ -3615,21 +3507,21 @@ msgid "" "requirements file like so::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:696 +#: ../source/guides/distributing-packages-using-setuptools.rst:442 msgid "" "The first line says to install your project and any dependencies. The second " "line overrides the \"bar\" dependency, such that it's fulfilled from VCS, " "not PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:700 +#: ../source/guides/distributing-packages-using-setuptools.rst:446 msgid "" "If, however, you want \"bar\" installed from a local directory in editable " "mode, the requirements file should look like this, with the local paths at " "the top of the file::" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:705 +#: ../source/guides/distributing-packages-using-setuptools.rst:451 msgid "" "Otherwise, the dependency will be fulfilled from PyPI, due to the " "installation order of the requirements file. For more on requirements " @@ -3638,22 +3530,22 @@ msgid "" "Support>` section of the pip docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:709 +#: ../source/guides/distributing-packages-using-setuptools.rst:455 msgid "" "Lastly, if you don't want to install any dependencies at all, you can run:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:716 +#: ../source/guides/distributing-packages-using-setuptools.rst:462 msgid "" "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:723 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 msgid "Packaging your project" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:725 +#: ../source/guides/distributing-packages-using-setuptools.rst:471 msgid "" "To have your project installable from a :term:`Package Index` like :term:" "`PyPI `, you'll need to create a :term:" @@ -3661,23 +3553,23 @@ msgid "" "Package>`\") for your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:730 +#: ../source/guides/distributing-packages-using-setuptools.rst:476 msgid "" "Before you can build wheels and sdists for your project, you'll need to " "install the ``build`` package:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:747 +#: ../source/guides/distributing-packages-using-setuptools.rst:493 msgid "Source distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:749 +#: ../source/guides/distributing-packages-using-setuptools.rst:495 msgid "" "Minimally, you should create a :term:`Source Distribution `:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:765 +#: ../source/guides/distributing-packages-using-setuptools.rst:511 msgid "" "A \"source distribution\" is unbuilt (i.e. it's not a :term:`Built " "Distribution`), and requires a build step when installed by pip. Even if " @@ -3686,11 +3578,11 @@ msgid "" "`setup.py` and/or :file:`setup.cfg`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:773 +#: ../source/guides/distributing-packages-using-setuptools.rst:519 msgid "Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:775 +#: ../source/guides/distributing-packages-using-setuptools.rst:521 msgid "" "You should also create a wheel for your project. A wheel is a :term:`built " "package ` that can be installed without needing to go " @@ -3698,95 +3590,95 @@ msgid "" "the end user than installing from a source distribution." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:780 +#: ../source/guides/distributing-packages-using-setuptools.rst:526 msgid "" "If your project is pure Python then you'll be creating a :ref:`\"Pure Python " "Wheel\" (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:783 +#: ../source/guides/distributing-packages-using-setuptools.rst:529 msgid "" "If your project contains compiled extensions, then you'll be creating what's " "called a :ref:`*Platform Wheel* (see section below) `." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:786 +#: ../source/guides/distributing-packages-using-setuptools.rst:532 msgid "" "If your project also supports Python 2 *and* contains no C extensions, then " "you should create what's called a *Universal Wheel* by adding the following " "to your :file:`setup.cfg` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:795 +#: ../source/guides/distributing-packages-using-setuptools.rst:541 msgid "" "Only use this setting if your project does not have any C extensions *and* " "supports Python 2 and 3." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:802 +#: ../source/guides/distributing-packages-using-setuptools.rst:548 msgid "Pure Python Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:804 +#: ../source/guides/distributing-packages-using-setuptools.rst:550 msgid "" "*Pure Python Wheels* contain no compiled extensions, and therefore only " "require a single Python wheel." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:807 -#: ../source/guides/distributing-packages-using-setuptools.rst:836 +#: ../source/guides/distributing-packages-using-setuptools.rst:553 +#: ../source/guides/distributing-packages-using-setuptools.rst:582 msgid "To build the wheel:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:821 +#: ../source/guides/distributing-packages-using-setuptools.rst:567 msgid "" "The ``wheel`` package will detect that the code is pure Python, and build a " "wheel that's named such that it's usable on any Python 3 installation. For " "details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:825 +#: ../source/guides/distributing-packages-using-setuptools.rst:571 msgid "" "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " "files for you; this is useful when you don't need multiple wheels." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:831 +#: ../source/guides/distributing-packages-using-setuptools.rst:577 msgid "Platform Wheels" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:833 +#: ../source/guides/distributing-packages-using-setuptools.rst:579 msgid "" "*Platform Wheels* are wheels that are specific to a certain platform like " "Linux, macOS, or Windows, usually due to containing compiled extensions." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:851 +#: ../source/guides/distributing-packages-using-setuptools.rst:597 msgid "" "The ``wheel`` package will detect that the code is not pure Python, and " "build a wheel that's named such that it's only usable on the platform that " "it was built on. For details on the naming of wheel files, see :pep:`425`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:857 +#: ../source/guides/distributing-packages-using-setuptools.rst:603 msgid "" ":term:`PyPI ` currently supports uploads of " "platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " "Details of the latter are defined in :pep:`513`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:865 +#: ../source/guides/distributing-packages-using-setuptools.rst:611 msgid "Uploading your Project to PyPI" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:867 +#: ../source/guides/distributing-packages-using-setuptools.rst:613 msgid "" "When you ran the command to create your distribution, a new directory ``dist/" "`` was created under your project's root directory. That's where you'll find " "your distribution file(s) to upload." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:871 +#: ../source/guides/distributing-packages-using-setuptools.rst:617 msgid "" "These files are only created when you run the command to create your " "distribution. This means that any time you change the source of your project " @@ -3794,7 +3686,7 @@ msgid "" "these files again before you can distribute the changes to PyPI." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:876 +#: ../source/guides/distributing-packages-using-setuptools.rst:622 msgid "" "Before releasing on main PyPI repo, you might prefer training with the `PyPI " "test site `_ which is cleaned on a semi regular " @@ -3802,7 +3694,7 @@ msgid "" "order to use it." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:881 +#: ../source/guides/distributing-packages-using-setuptools.rst:627 msgid "" "In other resources you may encounter references to using ``python setup.py " "register`` and ``python setup.py upload``. These methods of registering and " @@ -3811,7 +3703,7 @@ msgid "" "username and password to be intercepted during transmission." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:887 +#: ../source/guides/distributing-packages-using-setuptools.rst:633 msgid "" "The reStructuredText parser used on PyPI is **not** Sphinx! Furthermore, to " "ensure safety of all users, certain kinds of URLs and directives are " @@ -3821,78 +3713,78 @@ msgid "" "by running :std:doc:`twine check ` on your package files:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:900 +#: ../source/guides/distributing-packages-using-setuptools.rst:646 msgid "Create an account" msgstr "建立帳戶" -#: ../source/guides/distributing-packages-using-setuptools.rst:902 +#: ../source/guides/distributing-packages-using-setuptools.rst:648 msgid "" "First, you need a :term:`PyPI ` user account. " "You can create an account `using the form on the PyPI website `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:906 +#: ../source/guides/distributing-packages-using-setuptools.rst:652 msgid "" "Now you'll create a PyPI `API token`_ so you will be able to securely upload " "your project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:909 +#: ../source/guides/distributing-packages-using-setuptools.rst:655 msgid "" "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " "token`_; don't limit its scope to a particular project, since you are " "creating a new project." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:913 +#: ../source/guides/distributing-packages-using-setuptools.rst:659 msgid "" "**Don't close the page until you have copied and saved the token — you won't " "see that token again.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:916 +#: ../source/guides/distributing-packages-using-setuptools.rst:662 msgid "" "To avoid having to copy and paste the token every time you upload, you can " "create a :file:`$HOME/.pypirc` file:" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:925 +#: ../source/guides/distributing-packages-using-setuptools.rst:671 msgid "**Be aware that this stores your token in plaintext.**" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:927 +#: ../source/guides/distributing-packages-using-setuptools.rst:673 #: ../source/guides/migrating-to-pypi-org.rst:74 #: ../source/guides/migrating-to-pypi-org.rst:113 -#: ../source/guides/using-testpypi.rst:83 +#: ../source/guides/using-testpypi.rst:84 msgid "" "For more details, see the :ref:`specification ` for :file:`.pypirc`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:933 +#: ../source/guides/distributing-packages-using-setuptools.rst:679 msgid "Upload your distributions" msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:935 +#: ../source/guides/distributing-packages-using-setuptools.rst:681 msgid "" "Once you have an account you can upload your distributions to :term:`PyPI " "` using :ref:`twine`." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:938 +#: ../source/guides/distributing-packages-using-setuptools.rst:684 msgid "" "The process for uploading a release is the same regardless of whether or not " "the project already exists on PyPI - if it doesn't exist yet, it will be " "automatically created when the first release is uploaded." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:942 +#: ../source/guides/distributing-packages-using-setuptools.rst:688 msgid "" "For the second and subsequent releases, PyPI only requires that the version " "number of the new release differ from any previous releases." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:949 +#: ../source/guides/distributing-packages-using-setuptools.rst:695 msgid "" "You can see if your package has successfully uploaded by navigating to the " "URL ``https://pypi.org/project/`` where ``sampleproject`` is " @@ -3900,7 +3792,7 @@ msgid "" "your project to appear on the site." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:956 +#: ../source/guides/distributing-packages-using-setuptools.rst:702 #: ../source/tutorials/installing-packages.rst:670 msgid "" "Depending on your platform, this may require root or Administrator access. :" @@ -3908,14 +3800,6 @@ msgid "" "the default behavior `_." msgstr "" -#: ../source/guides/distributing-packages-using-setuptools.rst:962 -msgid "" -"Specifically, the \"console_script\" approach generates ``.exe`` files on " -"Windows, which are necessary because the OS special-cases ``.exe`` files. " -"Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher for " -"Windows <397>` allow scripts to be used in many cases, but not all." -msgstr "" - #: ../source/guides/dropping-older-python-versions.rst:5 msgid "Dropping support for older Python versions" msgstr "" @@ -4029,96 +3913,87 @@ msgid "" msgstr "" #: ../source/guides/dropping-older-python-versions.rst:81 -#: ../source/specifications/core-metadata.rst:149 -#: ../source/specifications/core-metadata.rst:473 -#: ../source/specifications/core-metadata.rst:497 -#: ../source/specifications/core-metadata.rst:538 -#: ../source/specifications/core-metadata.rst:594 -#: ../source/specifications/core-metadata.rst:727 -#: ../source/specifications/core-metadata.rst:757 -#: ../source/specifications/core-metadata.rst:798 -#: ../source/specifications/core-metadata.rst:820 -msgid "Examples::" +msgid "Examples:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:86 +#: ../source/guides/dropping-older-python-versions.rst:88 msgid "" "The way to set those values is within the call to ``setup`` within your :" "file:`setup.py` script. This will insert the ``Requires-Python`` metadata " "values based on the argument you provide in ``python_requires``." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:101 +#: ../source/guides/dropping-older-python-versions.rst:103 msgid "3. Validating the Metadata before publishing" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:103 +#: ../source/guides/dropping-older-python-versions.rst:105 msgid "" "Within a Python source package (the zip or the tar-gz file you download) is " "a text file called PKG-INFO." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:105 +#: ../source/guides/dropping-older-python-versions.rst:107 msgid "" "This file is generated by :ref:`distutils` or :ref:`setuptools` when it " "generates the source package. The file contains a set of keys and values, " "the list of keys is part of the PyPa standard metadata format." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:108 +#: ../source/guides/dropping-older-python-versions.rst:110 msgid "You can see the contents of the generated file like this:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:114 +#: ../source/guides/dropping-older-python-versions.rst:116 msgid "Validate that the following is in place, before publishing the package:" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:116 +#: ../source/guides/dropping-older-python-versions.rst:118 msgid "" "If you have upgraded correctly, the Metadata-Version value should be 1.2 or " "higher." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:117 +#: ../source/guides/dropping-older-python-versions.rst:119 msgid "" "The Requires-Python field is set and matches your specification in setup.py." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:120 +#: ../source/guides/dropping-older-python-versions.rst:122 msgid "4. Using Twine to publish" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:122 +#: ../source/guides/dropping-older-python-versions.rst:124 msgid "" "Twine has a number of advantages, apart from being faster it is now the " "supported method for publishing packages." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:124 +#: ../source/guides/dropping-older-python-versions.rst:126 msgid "Make sure you are using the newest version of Twine, at least 1.9." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:127 +#: ../source/guides/dropping-older-python-versions.rst:129 msgid "Dropping a Python release" msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:129 +#: ../source/guides/dropping-older-python-versions.rst:131 msgid "" "Once you have published a package with the Requires-Python metadata, you can " "then make a further update removing that Python runtime from support." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:131 +#: ../source/guides/dropping-older-python-versions.rst:133 msgid "It must be done in this order for the automated fallback to work." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:133 +#: ../source/guides/dropping-older-python-versions.rst:135 msgid "" "For example, you published the Requires-Python: \">=2.7\" as version 1.0.0 " "of your package." msgstr "" -#: ../source/guides/dropping-older-python-versions.rst:135 +#: ../source/guides/dropping-older-python-versions.rst:137 msgid "" "If you were then to update the version string to \">=3.5\", and publish a " "new version 2.0.0 of your package, any users running Pip 9.0+ from version " @@ -4133,9 +4008,9 @@ msgstr "" #: ../source/guides/hosting-your-own-index.rst:8 msgid "" "If you wish to host your own simple repository [1]_, you can either use a " -"software package like :doc:`devpi ` or you can use simply " -"create the proper directory structure and use any web server that can serve " -"static files and generate an autoindex." +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." msgstr "" #: ../source/guides/hosting-your-own-index.rst:13 @@ -4417,7 +4292,7 @@ msgid "" msgstr "" #: ../source/guides/installing-scientific-packages.rst:100 -#: ../source/key_projects.rst:676 +#: ../source/key_projects.rst:675 msgid "Spack" msgstr "" @@ -4522,6 +4397,7 @@ msgid "" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:52 +#: ../source/specifications/entry-points.rst:114 msgid "For example:" msgstr "" @@ -4550,7 +4426,7 @@ msgid "To see the full list of commands pipx offers, run:" msgstr "" #: ../source/guides/installing-stand-alone-command-line-tools.rst:131 -msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +msgid "You can learn more about pipx at https://pipx.pypa.io/." msgstr "" #: ../source/guides/installing-using-linux-tools.rst:5 @@ -4728,7 +4604,7 @@ msgid "Create and activate a virtual environment" msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:152 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 msgid "Prepare pip" msgstr "" @@ -4787,33 +4663,33 @@ msgstr "" #: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 msgid "" -"To create a virtual environment, go to your project's directory and run " -"``venv``. This will create a new virtual environment in a local folder ``." -"venv``:" +"To create a virtual environment, go to your project's directory and run the " +"following command. This will create a new virtual environment in a local " +"folder named ``.venv``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:63 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 msgid "" "The second argument is the location to create the virtual environment. " "Generally, you can just create this in your project and call it ``.venv``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:66 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 msgid "" "``venv`` will create a virtual Python installation in the ``.venv`` folder." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:68 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 msgid "" "You should exclude your virtual environment directory from your version " "control system using ``.gitignore`` or similar." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:73 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 msgid "Activate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:75 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 msgid "" "Before you can start installing or using packages in your virtual " "environment you'll need to ``activate`` it. Activating a virtual environment " @@ -4821,155 +4697,155 @@ msgid "" "into your shell's ``PATH``." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:92 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 msgid "" "To confirm the virtual environment is activated, check the location of your " "Python interpreter:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:107 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 msgid "" "While the virtual environment is active, the above command will output a " "filepath that includes the ``.venv`` directory, by ending with the following:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:123 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 msgid "" "While a virtual environment is activated, pip will install packages into " "that specific environment. This enables you to import and use packages in " "your Python application." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:129 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 msgid "Deactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:131 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 msgid "" "If you want to switch projects or leave your virtual environment, " "``deactivate`` the environment:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:139 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 msgid "" "Closing your shell will deactivate the virtual environment. If you open a " "new shell window and want to use the virtual environment, reactivate it." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:144 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 msgid "Reactivate a virtual environment" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:146 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 msgid "" "If you want to reactivate an existing virtual environment, follow the same " "instructions about activating a virtual environment. There's no need to " "create a new virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:154 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 msgid "" ":ref:`pip` is the reference Python package manager. It's used to install and " "update packages into a virtual environment." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:160 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 msgid "" "The Python installers for macOS include pip. On Linux, you may have to " "install an additional package such as ``python3-pip``. You can make sure " "that pip is up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:169 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 msgid "" "Afterwards, you should have the latest version of pip installed in your user " "site:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:178 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 msgid "" "The Python installers for Windows include pip. You can make sure that pip is " "up-to-date by running:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:186 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 msgid "Afterwards, you should have the latest version of pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:194 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 #, fuzzy #| msgid "Installing packages" msgid "Install packages using pip" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:196 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 msgid "" "When your virtual environment is activated, you can install packages. Use " "the ``pip install`` command to install packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:200 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 #, fuzzy #| msgid "Installing packages" msgid "Install a package" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:202 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 msgid "" "For example,let's install the `Requests`_ library from the :term:`Python " "Package Index (PyPI)`:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:217 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 msgid "" "pip should download requests and all of its dependencies and install them:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:238 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 #, fuzzy #| msgid "Installing packages" msgid "Install a specific package version" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:240 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 msgid "" "pip allows you to specify which version of a package to install using :term:" "`version specifiers `. For example, to install a specific " "version of ``requests``:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:256 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 msgid "To install the latest ``2.x`` release of requests:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:270 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 msgid "To install pre-release versions of packages, use the ``--pre`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:286 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 #, fuzzy msgid "Install extras" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:288 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 msgid "" "Some packages have optional `extras`_. You can tell pip to install these by " "specifying the extra in brackets:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:308 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 #, fuzzy #| msgid "Installing packages" msgid "Install a package from source" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:310 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 msgid "" "pip can install a package directly from its source code. For example, to " "install the source code in the ``google-auth`` directory:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:327 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 msgid "" "Additionally, pip can install packages from source in :doc:`development mode " "`, meaning that changes to the source " @@ -4977,108 +4853,108 @@ msgid "" "re-install:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:346 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 msgid "Install from version control systems" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:348 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 msgid "" "pip can install packages directly from their version control system. For " "example, you can install directly from a git repository:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:355 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 msgid "" "For more information on supported version control systems and syntax, see " "pip's documentation on :ref:`VCS Support `." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:360 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 msgid "Install from local archives" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:362 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 msgid "" "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " "wheel, or tar file) you can install it directly with pip:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:377 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 msgid "" "If you have a directory containing archives of multiple packages, you can " "tell pip to look for packages there and not to use the :term:`Python Package " "Index (PyPI)` at all:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:393 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 msgid "" "This is useful if you are installing packages on a system with limited " "connectivity or if you want to strictly control the origin of distribution " "packages." msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:399 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 #, fuzzy #| msgid "Installing packages" msgid "Install from other package indexes" msgstr "安裝軟體套件" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:401 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 msgid "" "If you want to download packages from a different index than the :term:" "`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:416 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 msgid "" "If you want to allow packages from both the :term:`Python Package Index " "(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " "instead:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:433 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 #: ../source/tutorials/installing-packages.rst:393 msgid "Upgrading packages" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:435 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 msgid "" "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " "to install the latest version of ``requests`` and all of its dependencies:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:451 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 msgid "Using a requirements file" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:453 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 msgid "" "Instead of installing packages individually, pip allows you to declare all " "dependencies in a :ref:`Requirements File `. For " "example you could create a :file:`requirements.txt` file containing:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:462 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 msgid "" "And tell pip to install all of the packages in this file using the ``-r`` " "flag:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:477 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 msgid "Freezing dependencies" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:479 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 msgid "" "Pip can export a list of all installed packages and their versions using the " "``freeze`` command:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:494 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 msgid "Which will output a list of package specifiers such as:" msgstr "" -#: ../source/guides/installing-using-pip-and-virtual-environments.rst:510 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 msgid "" "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " "Files` that can re-create the exact versions of all packages installed in an " @@ -5529,13 +5405,12 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:69 #: ../source/guides/modernize-setup-py-project.rst:113 -#: ../source/guides/modernize-setup-py-project.rst:246 -msgid ":ref:`declaring-build-dependencies`" +msgid ":ref:`pyproject-build-system-table`" msgstr "" #: ../source/guides/modernize-setup-py-project.rst:70 #: ../source/guides/modernize-setup-py-project.rst:131 -#: ../source/guides/modernize-setup-py-project.rst:248 +#: ../source/guides/modernize-setup-py-project.rst:247 msgid ":doc:`pip:reference/build-system/pyproject-toml`" msgstr "" @@ -5605,7 +5480,7 @@ msgstr "" #: ../source/guides/modernize-setup-py-project.rst:164 msgid "" -"Read :ref:`declaring-project-metadata` for the full specification of the " +"Read :ref:`pyproject-project-table` for the full specification of the " "content allowed in the ``[project]`` table." msgstr "" @@ -5644,11 +5519,13 @@ msgid "" "This file can be as minimalistic as this:" msgstr "" -#: ../source/guides/modernize-setup-py-project.rst:247 -msgid ":ref:`declaring-project-metadata`" -msgstr "" +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "專案名稱" -#: ../source/guides/modernize-setup-py-project.rst:249 +#: ../source/guides/modernize-setup-py-project.rst:248 msgid ":doc:`setuptools:build_meta`" msgstr "" @@ -6265,11 +6142,11 @@ msgid "" "cpp_extension_modules.html>`_" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:3 +#: ../source/guides/packaging-namespace-packages.rst:5 msgid "Packaging namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:5 +#: ../source/guides/packaging-namespace-packages.rst:7 msgid "" "Namespace packages allow you to split the sub-packages and modules within a " "single :term:`package ` across multiple, separate :term:" @@ -6278,19 +6155,19 @@ msgid "" "have the following package structure:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:24 +#: ../source/guides/packaging-namespace-packages.rst:26 msgid "And you use this package in your code like so::" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:29 +#: ../source/guides/packaging-namespace-packages.rst:31 msgid "Then you can break these sub-packages into two separate distributions:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:48 +#: ../source/guides/packaging-namespace-packages.rst:50 msgid "Each sub-package can now be separately installed, used, and versioned." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:50 +#: ../source/guides/packaging-namespace-packages.rst:52 msgid "" "Namespace packages can be useful for a large collection of loosely-related " "packages (such as a large corpus of client libraries for multiple products " @@ -6301,17 +6178,17 @@ msgid "" "mynamespace_subpackage_a as subpackage_a`` to keep the import object short)." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:60 +#: ../source/guides/packaging-namespace-packages.rst:62 msgid "Creating a namespace package" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:62 +#: ../source/guides/packaging-namespace-packages.rst:64 msgid "" "There are currently two different approaches to creating namespace packages, " "from which the latter is discouraged:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:65 +#: ../source/guides/packaging-namespace-packages.rst:67 msgid "" "Use `native namespace packages`_. This type of namespace package is defined " "in :pep:`420` and is available in Python 3.3 and later. This is recommended " @@ -6319,17 +6196,17 @@ msgid "" "installation via ``pip``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:69 +#: ../source/guides/packaging-namespace-packages.rst:71 msgid "" "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " "packages`_ and `pkg_resources-style namespace packages`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:73 +#: ../source/guides/packaging-namespace-packages.rst:75 msgid "Native namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:75 +#: ../source/guides/packaging-namespace-packages.rst:77 msgid "" "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " "is required to create a native namespace package is that you just omit :file:" @@ -6337,7 +6214,7 @@ msgid "" "structure (following :ref:`src-layout `):" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:92 +#: ../source/guides/packaging-namespace-packages.rst:94 msgid "" "It is extremely important that every distribution that uses the namespace " "package omits the :file:`__init__.py` or uses a pkgutil-style :file:" @@ -6345,7 +6222,7 @@ msgid "" "logic to fail and the other sub-packages will not be importable." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:97 +#: ../source/guides/packaging-namespace-packages.rst:99 msgid "" "The ``src-layout`` directory structure allows automatic discovery of " "packages by most :term:`build backends `. See :ref:`src-" @@ -6354,27 +6231,27 @@ msgid "" "configured in the top-level :file:`pyproject.toml`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:115 +#: ../source/guides/packaging-namespace-packages.rst:117 msgid "The same can be accomplished with a :file:`setup.cfg`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:127 +#: ../source/guides/packaging-namespace-packages.rst:129 msgid "Or :file:`setup.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:140 +#: ../source/guides/packaging-namespace-packages.rst:142 msgid "" ":ref:`setuptools` will search the directory structure for implicit namespace " "packages by default." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:143 +#: ../source/guides/packaging-namespace-packages.rst:145 msgid "" "A complete working example of two native namespace packages can be found in " "the `native namespace package example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:149 +#: ../source/guides/packaging-namespace-packages.rst:151 msgid "" "Because native and pkgutil-style namespace packages are largely compatible, " "you can use native namespace packages in the distributions that only support " @@ -6382,11 +6259,11 @@ msgid "" "to support Python 2 and 3." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:156 +#: ../source/guides/packaging-namespace-packages.rst:158 msgid "Legacy namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:158 +#: ../source/guides/packaging-namespace-packages.rst:160 msgid "" "These two methods, that were used to create namespace packages prior to :pep:" "`420`, are now considered to be obsolete and should not be used unless you " @@ -6394,13 +6271,13 @@ msgid "" "`pkg_resources ` has been deprecated." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:163 +#: ../source/guides/packaging-namespace-packages.rst:165 msgid "" "To migrate an existing package, all packages sharing the namespace must be " "migrated simultaneously." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:165 +#: ../source/guides/packaging-namespace-packages.rst:167 msgid "" "While native namespace packages and pkgutil-style namespace packages are " "largely compatible, pkg_resources-style namespace packages are not " @@ -6408,11 +6285,11 @@ msgid "" "in different distributions that provide packages to the same namespace." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:172 +#: ../source/guides/packaging-namespace-packages.rst:174 msgid "pkgutil-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:174 +#: ../source/guides/packaging-namespace-packages.rst:176 msgid "" "Python 2.3 introduced the :doc:`pkgutil ` module and " "the :py:func:`python:pkgutil.extend_path` function. This can be used to " @@ -6421,21 +6298,21 @@ msgid "" "compatibility." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:179 +#: ../source/guides/packaging-namespace-packages.rst:181 msgid "" "To create a pkgutil-style namespace package, you need to provide an :file:" "`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:193 -#: ../source/guides/packaging-namespace-packages.rst:240 +#: ../source/guides/packaging-namespace-packages.rst:195 +#: ../source/guides/packaging-namespace-packages.rst:242 msgid "" "The :file:`__init__.py` file for the namespace package needs to contain the " "following:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:200 -#: ../source/guides/packaging-namespace-packages.rst:247 +#: ../source/guides/packaging-namespace-packages.rst:202 +#: ../source/guides/packaging-namespace-packages.rst:249 msgid "" "**Every** distribution that uses the namespace package must include such an :" "file:`__init__.py`. If any distribution does not, it will cause the " @@ -6443,17 +6320,17 @@ msgid "" "Any additional code in :file:`__init__.py` will be inaccessible." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:205 +#: ../source/guides/packaging-namespace-packages.rst:207 msgid "" "A complete working example of two pkgutil-style namespace packages can be " "found in the `pkgutil namespace example project`_." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:215 +#: ../source/guides/packaging-namespace-packages.rst:217 msgid "pkg_resources-style namespace packages" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:217 +#: ../source/guides/packaging-namespace-packages.rst:219 msgid "" ":doc:`Setuptools ` provides the `pkg_resources." "declare_namespace`_ function and the ``namespace_packages`` argument to :" @@ -6465,19 +6342,19 @@ msgid "" "compatible and it's not advisable to try to migrate an existing package." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:226 +#: ../source/guides/packaging-namespace-packages.rst:228 msgid "" "To create a pkg_resources-style namespace package, you need to provide an :" "file:`__init__.py` file for the namespace package:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:252 +#: ../source/guides/packaging-namespace-packages.rst:254 msgid "" "Some older recommendations advise the following in the namespace package :" "file:`__init__.py`:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:262 +#: ../source/guides/packaging-namespace-packages.rst:264 msgid "" "The idea behind this was that in the rare case that setuptools isn't " "available packages would fall-back to the pkgutil-style packages. This isn't " @@ -6486,13 +6363,13 @@ msgid "" "package should just explicitly depend on setuptools via ``install_requires``." msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:269 +#: ../source/guides/packaging-namespace-packages.rst:271 msgid "" "Finally, every distribution must provide the ``namespace_packages`` argument " "to :func:`~setuptools.setup` in :file:`setup.py`. For example:" msgstr "" -#: ../source/guides/packaging-namespace-packages.rst:283 +#: ../source/guides/packaging-namespace-packages.rst:285 msgid "" "A complete working example of two pkg_resources-style namespace packages can " "be found in the `pkg_resources namespace example project`_." @@ -6788,44 +6665,52 @@ msgstr "翻譯" msgid "Single-sourcing the package version" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:8 +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Todo" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:7 +msgid "Update this page for build backends other than setuptools." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:9 msgid "" "There are many techniques to maintain a single source of truth for the " "version number of your project:" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:11 +#: ../source/guides/single-sourcing-package-version.rst:12 msgid "" "Read the file in :file:`setup.py` and get the version. Example (from `pip " "setup.py `_)::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:38 +#: ../source/guides/single-sourcing-package-version.rst:39 msgid "" "As of the release of setuptools 46.4.0, one can accomplish the same thing by " "instead placing the following in the project's :file:`setup.cfg` file " "(replacing \"package\" with the import name of the package):" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:48 +#: ../source/guides/single-sourcing-package-version.rst:49 msgid "" "As of the release of setuptools 61.0.0, one can specify the version " "dynamically in the project's :file:`pyproject.toml` file." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:60 +#: ../source/guides/single-sourcing-package-version.rst:61 msgid "" "Please be aware that declarative config indicators, including the ``attr:`` " "directive, are not supported in parameters to :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:64 +#: ../source/guides/single-sourcing-package-version.rst:65 msgid "" "Use an external build tool that either manages updating both locations, or " "offers an API that both locations can use." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:67 +#: ../source/guides/single-sourcing-package-version.rst:68 msgid "" "Few tools you could use, in no particular order, and not necessarily " "complete: `bump2version `_, `changes " @@ -6833,39 +6718,39 @@ msgid "" "commitizen>`_, `zest.releaser `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:74 +#: ../source/guides/single-sourcing-package-version.rst:75 msgid "" "Set the value to a ``__version__`` global variable in a dedicated module in " "your project (e.g. :file:`version.py`), then have :file:`setup.py` read and " "``exec`` the value into a variable." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:85 +#: ../source/guides/single-sourcing-package-version.rst:86 msgid "" "Example using this technique: `warehouse `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:87 +#: ../source/guides/single-sourcing-package-version.rst:88 msgid "" "Place the value in a simple ``VERSION`` text file and have both :file:`setup." "py` and the project code read it." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:95 +#: ../source/guides/single-sourcing-package-version.rst:96 msgid "" "An advantage with this technique is that it's not specific to Python. Any " "tool can read the version." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:100 +#: ../source/guides/single-sourcing-package-version.rst:101 msgid "" "With this approach you must make sure that the ``VERSION`` file is included " "in all your source and binary distributions (e.g. add ``include VERSION`` to " "your :file:`MANIFEST.in`)." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:104 +#: ../source/guides/single-sourcing-package-version.rst:105 msgid "" "Set the value in :file:`setup.py`, and have the project code use the " "``importlib.metadata`` API to fetch the value at runtime. (``importlib." @@ -6874,52 +6759,52 @@ msgid "" "be fetched with the API as follows::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:119 +#: ../source/guides/single-sourcing-package-version.rst:120 msgid "" "Be aware that the ``importlib.metadata`` API only knows about what's in the " "installation metadata, which is not necessarily the code that's currently " "imported." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:123 +#: ../source/guides/single-sourcing-package-version.rst:124 msgid "" "If a project uses this method to fetch its version at runtime, then its " "``install_requires`` value needs to be edited to install ``importlib-" "metadata`` on pre-3.8 versions of Python like so::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:137 +#: ../source/guides/single-sourcing-package-version.rst:138 msgid "" "An older (and less efficient) alternative to ``importlib.metadata`` is the " "``pkg_resources`` API provided by ``setuptools``::" msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:143 +#: ../source/guides/single-sourcing-package-version.rst:144 msgid "" "If a project uses ``pkg_resources`` to fetch its own version at runtime, " "then ``setuptools`` must be added to the project's ``install_requires`` list." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:147 +#: ../source/guides/single-sourcing-package-version.rst:148 msgid "" "Example using this technique: `setuptools `_." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:150 +#: ../source/guides/single-sourcing-package-version.rst:151 msgid "" "Set the value to ``__version__`` in ``sample/__init__.py`` and import " "``sample`` in :file:`setup.py`." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:164 +#: ../source/guides/single-sourcing-package-version.rst:165 msgid "" "Although this technique is common, beware that it will fail if ``sample/" "__init__.py`` imports packages from ``install_requires`` dependencies, which " "will very likely not be installed yet when :file:`setup.py` is run." msgstr "" -#: ../source/guides/single-sourcing-package-version.rst:170 +#: ../source/guides/single-sourcing-package-version.rst:171 msgid "" "Keep the version number in the tags of a version control system (Git, " "Mercurial, etc) instead of in the code, and automatically extract it from " @@ -7672,8 +7557,8 @@ msgstr "" #: ../source/guides/using-testpypi.rst:75 msgid "" -"If you want to avoid entering your username, you can configure TestPyPI in " -"your :file:`$HOME/.pypirc`:" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:5 @@ -7790,91 +7675,128 @@ msgid "Basic information" msgstr "" #: ../source/guides/writing-pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:120 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:152 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 msgid "" "Put the name of your project on PyPI. This field is required and is the only " "field that cannot be marked as dynamic." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:134 +#: ../source/guides/writing-pyproject-toml.rst:132 +msgid "" +"The project name must consists of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:136 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:125 +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:164 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 #, fuzzy #| msgid "List keywords that describe your project." msgid "Put the version of your project." msgstr "列出描述您的項目的關鍵字。" -#: ../source/guides/writing-pyproject-toml.rst:141 +#: ../source/guides/writing-pyproject-toml.rst:153 msgid "" "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " "release) are possible; see the :ref:`specification ` for " "full details." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:145 +#: ../source/guides/writing-pyproject-toml.rst:157 msgid "This field is required, although it is often marked as dynamic using" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:155 +#: ../source/guides/writing-pyproject-toml.rst:164 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult :ref:`Single sourcing the version` for more " +"details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:170 msgid "Dependencies and requirements" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:158 -#: ../source/specifications/declaring-project-metadata.rst:275 +#: ../source/guides/writing-pyproject-toml.rst:173 +#: ../source/specifications/pyproject-toml.rst:354 msgid "``dependencies``/``optional-dependencies``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:160 +#: ../source/guides/writing-pyproject-toml.rst:175 msgid "If your project has dependencies, list them like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:187 msgid "" "See :ref:`Dependency specifiers ` for the full syntax " "you can use to constrain versions." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:175 +#: ../source/guides/writing-pyproject-toml.rst:190 msgid "" "You may want to make some of your dependencies optional, if they are only " "needed for a specific feature of your package. In that case, put them in " "``optional-dependencies``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:188 +#: ../source/guides/writing-pyproject-toml.rst:203 msgid "" "Each of the keys defines a \"packaging extra\". In the example above, one " "could use, e.g., ``pip install your-project-name[gui]`` to install your " "project with GUI support, adding the PyQt5 dependency." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:194 -#: ../source/specifications/declaring-project-metadata.rst:66 -#: ../source/specifications/declaring-project-metadata.rst:147 +#: ../source/guides/writing-pyproject-toml.rst:212 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:226 msgid "``requires-python``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:196 +#: ../source/guides/writing-pyproject-toml.rst:214 msgid "" "This lets you declare the minimum version of Python that you support " "[#requires-python-upper-bounds]_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:207 +#: ../source/guides/writing-pyproject-toml.rst:226 msgid "Creating executable scripts" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:209 +#: ../source/guides/writing-pyproject-toml.rst:228 msgid "" "To install a command as part of your package, declare it in the ``[project." "scripts]`` table." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:217 +#: ../source/guides/writing-pyproject-toml.rst:236 msgid "" "In this example, after installing your project, a ``spam-cli`` command will " "be available. Executing this command will do the equivalent of ``from spam " "import main_cli; main_cli()``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:221 +#: ../source/guides/writing-pyproject-toml.rst:240 msgid "" "On Windows, scripts packaged this way need a terminal, so if you launch them " "from within a graphical application, they will make a terminal pop up. To " @@ -7882,129 +7804,180 @@ msgid "" "of ``[project.scripts]``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:231 +#: ../source/guides/writing-pyproject-toml.rst:250 msgid "" "In that case, launching your script from the command line will give back " "control immediately, leaving the script to run in the background." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:253 msgid "" "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " "is only relevant on Windows." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:240 +#: ../source/guides/writing-pyproject-toml.rst:259 msgid "About your project" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:243 -#: ../source/specifications/declaring-project-metadata.rst:172 +#: ../source/guides/writing-pyproject-toml.rst:262 +#: ../source/specifications/pyproject-toml.rst:251 msgid "``authors``/``maintainers``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:245 +#: ../source/guides/writing-pyproject-toml.rst:264 msgid "" "Both of these fields contain lists of people identified by a name and/or an " "email address." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:265 +#: ../source/guides/writing-pyproject-toml.rst:284 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:177 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:286 msgid "" "This should be a one-line description of your project, to show as the " -"\"headline\" of your project page on PyPI (`example `_)." +"\"headline\" of your project page on PyPI (`example `_), and " +"other places such as lists of search results (`example `_)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:275 -#: ../source/specifications/declaring-project-metadata.rst:65 -#: ../source/specifications/declaring-project-metadata.rst:108 +#: ../source/guides/writing-pyproject-toml.rst:297 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:187 msgid "``readme``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:277 +#: ../source/guides/writing-pyproject-toml.rst:299 msgid "" "This is a longer description of your project, to display on your project " "page on PyPI. Typically, your project will have a ``README.md`` or ``README." "rst`` file and you just put its file name here." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:286 +#: ../source/guides/writing-pyproject-toml.rst:308 msgid "The README's format is auto-detected from the extension:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:288 -msgid "``README.md`` → Markdown," +#: ../source/guides/writing-pyproject-toml.rst:310 +msgid "``README.md`` → `GitHub-flavored Markdown `_," msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:289 -msgid "``README.rst`` → reStructuredText (without Sphinx extensions)." +#: ../source/guides/writing-pyproject-toml.rst:311 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:291 +#: ../source/guides/writing-pyproject-toml.rst:313 msgid "You can also specify the format explicitly, like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:304 +#: ../source/guides/writing-pyproject-toml.rst:324 +#: ../source/specifications/pyproject-toml.rst:140 +#: ../source/specifications/pyproject-toml.rst:236 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:326 msgid "" "This can take two forms. You can put your license in a file, typically " "``LICENSE`` or ``LICENSE.txt``, and link that file here:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:312 +#: ../source/guides/writing-pyproject-toml.rst:334 msgid "or you can write the name of the license:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:325 +#: ../source/guides/writing-pyproject-toml.rst:341 +msgid "" +"If you are using a standard, well-known license, it is not necessary to use " +"this field. Instead, you should one of the :ref:`classifiers` starting with " +"``License ::``. (As a general rule, it is a good idea to use a standard, " +"well-known license, both to avoid confusion and because some organizations " +"avoid software whose license is unapproved.)" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#: ../source/specifications/pyproject-toml.rst:139 +#: ../source/specifications/pyproject-toml.rst:293 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:351 msgid "" "This will help PyPI's search box to suggest your project when people search " "for these keywords." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:337 +#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/specifications/pyproject-toml.rst:133 +#: ../source/specifications/pyproject-toml.rst:303 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:365 msgid "" "A list of PyPI classifiers that apply to your project. Check the `full list " "of possibilities `_." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:349 -#: ../source/specifications/declaring-project-metadata.rst:68 -#: ../source/specifications/declaring-project-metadata.rst:234 +#: ../source/guides/writing-pyproject-toml.rst:392 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:403 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:313 msgid "``urls``" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:351 +#: ../source/guides/writing-pyproject-toml.rst:405 msgid "" "A list of URLs associated with your project, displayed on the left sidebar " "of your PyPI project page." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:363 +#: ../source/guides/writing-pyproject-toml.rst:417 msgid "" "Note that if the key contains spaces, it needs to be quoted, e.g., ``Website " "= \"https://example.com\"`` but ``\"Official Website\" = \"https://example." "com\"``." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:370 +#: ../source/guides/writing-pyproject-toml.rst:424 msgid "Advanced plugins" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:372 +#: ../source/guides/writing-pyproject-toml.rst:426 msgid "" "Some packages can be extended through plugins. Examples include Pytest_ and " "Pygments_. To create such a plugin, you need to declare it in a subtable of " "``[project.entry-points]`` like this:" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:381 +#: ../source/guides/writing-pyproject-toml.rst:435 msgid "See the :ref:`Plugin guide ` for more information." msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:386 +#: ../source/guides/writing-pyproject-toml.rst:440 msgid "A full example" msgstr "" -#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/guides/writing-pyproject-toml.rst:502 msgid "" "Think twice before applying an upper bound like ``requires-python = \"<= " "3.10\"`` here. `This blog post `_ contains some " @@ -8439,8 +8412,8 @@ msgstr "" #: ../source/key_projects.rst:236 msgid "" -"`Docs `__ | `GitHub `__ | `PyPI `__" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" msgstr "" #: ../source/key_projects.rst:240 @@ -8451,9 +8424,8 @@ msgstr "" #: ../source/key_projects.rst:247 msgid "" -":doc:`Docs ` | `Issues `__ | `GitHub `__" +":doc:`Docs ` | `Issues `__ | `GitHub `__" msgstr "" #: ../source/key_projects.rst:251 @@ -8512,13 +8484,12 @@ msgstr "" #: ../source/key_projects.rst:293 msgid "" "trove-classifiers is the canonical source for `classifiers on PyPI `_, which project maintainers use to `systematically " -"describe their projects `_ so that users can better find projects " -"that match their needs on the PyPI." +"pypi.org/classifiers/>`_, which project maintainers use to :ref:" +"`systematically describe their projects ` so that " +"users can better find projects that match their needs on the PyPI." msgstr "" -#: ../source/key_projects.rst:299 +#: ../source/key_projects.rst:298 msgid "" "The trove-classifiers package contains a list of valid classifiers and " "deprecated classifiers (which are paired with the classifiers that replace " @@ -8531,18 +8502,18 @@ msgid "" "classifiers." msgstr "" -#: ../source/key_projects.rst:313 +#: ../source/key_projects.rst:312 msgid "twine" msgstr "" -#: ../source/key_projects.rst:315 +#: ../source/key_projects.rst:314 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:320 +#: ../source/key_projects.rst:319 msgid "" "Twine is the primary tool developers use to upload packages to the Python " "Package Index or other Python package indexes. It is a command-line program " @@ -8551,18 +8522,18 @@ msgid "" "maintained, and it reliably works." msgstr "" -#: ../source/key_projects.rst:330 ../source/overview.rst:409 +#: ../source/key_projects.rst:329 ../source/overview.rst:409 msgid "virtualenv" msgstr "" -#: ../source/key_projects.rst:332 +#: ../source/key_projects.rst:331 msgid "" "`Docs `__ | `Issues " "`__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:337 +#: ../source/key_projects.rst:336 msgid "" "virtualenv is a tool for creating isolated Python :term:`Virtual " "Environments `, like :ref:`venv`. Unlike :ref:`venv`, " @@ -8573,42 +8544,42 @@ msgid "" "on :ref:`Creating and using Virtual Environments`." msgstr "" -#: ../source/key_projects.rst:349 +#: ../source/key_projects.rst:348 msgid "Warehouse" msgstr "" -#: ../source/key_projects.rst:351 +#: ../source/key_projects.rst:350 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:355 +#: ../source/key_projects.rst:354 msgid "" "The current codebase powering the :term:`Python Package Index (PyPI)`. It is " "hosted at `pypi.org `_. The default source for :ref:`pip` " "downloads." msgstr "" -#: ../source/key_projects.rst:363 +#: ../source/key_projects.rst:362 msgid "wheel" msgstr "" -#: ../source/key_projects.rst:365 +#: ../source/key_projects.rst:364 msgid "" "`Docs `__ | `Issues `__ | `GitHub `__ | " "`PyPI `__" msgstr "" -#: ../source/key_projects.rst:370 +#: ../source/key_projects.rst:369 msgid "" "Primarily, the wheel project offers the ``bdist_wheel`` :ref:`setuptools` " "extension for creating :term:`wheel distributions `. Additionally, " "it offers its own command line utility for creating and installing wheels." msgstr "" -#: ../source/key_projects.rst:374 +#: ../source/key_projects.rst:373 msgid "" "See also `auditwheel `__, a tool that " "package developers use to check and fix Python packages they are making in " @@ -8617,22 +8588,22 @@ msgid "" "link and include external shared libraries in a package." msgstr "" -#: ../source/key_projects.rst:383 +#: ../source/key_projects.rst:382 msgid "Non-PyPA Projects" msgstr "" -#: ../source/key_projects.rst:388 +#: ../source/key_projects.rst:387 msgid "buildout" msgstr "" -#: ../source/key_projects.rst:390 +#: ../source/key_projects.rst:389 msgid "" "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:395 +#: ../source/key_projects.rst:394 msgid "" "Buildout is a Python-based build system for creating, assembling and " "deploying applications from multiple parts, some of which may be non-Python-" @@ -8640,15 +8611,15 @@ msgid "" "software later." msgstr "" -#: ../source/key_projects.rst:402 +#: ../source/key_projects.rst:401 msgid "conda" msgstr "" -#: ../source/key_projects.rst:404 +#: ../source/key_projects.rst:403 msgid ":doc:`Docs `" msgstr "" -#: ../source/key_projects.rst:406 +#: ../source/key_projects.rst:405 msgid "" "conda is the package management tool for `Anaconda `__ Python installations. Anaconda Python is a distribution " @@ -8657,14 +8628,14 @@ msgid "" "where the installation of binary extensions is often difficult." msgstr "" -#: ../source/key_projects.rst:413 +#: ../source/key_projects.rst:412 msgid "" "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " "but provides many of their combined features in terms of package management, " "virtual environment management and deployment of binary extensions." msgstr "" -#: ../source/key_projects.rst:417 +#: ../source/key_projects.rst:416 msgid "" "Conda does not install packages from PyPI and can install only from the " "official Anaconda repositories, or anaconda.org (a place for user-" @@ -8677,17 +8648,17 @@ msgid "" "modifying their metadata." msgstr "" -#: ../source/key_projects.rst:430 +#: ../source/key_projects.rst:429 msgid "devpi" msgstr "" -#: ../source/key_projects.rst:432 +#: ../source/key_projects.rst:431 msgid "" "`Docs `__ | :gh:`Issues ` " "| `PyPI `__" msgstr "" -#: ../source/key_projects.rst:436 +#: ../source/key_projects.rst:435 msgid "" "devpi features a powerful PyPI-compatible server and PyPI proxy cache with a " "complementary command line tool to drive packaging, testing and release " @@ -8695,17 +8666,17 @@ msgid "" "interface." msgstr "" -#: ../source/key_projects.rst:444 +#: ../source/key_projects.rst:443 msgid "enscons" msgstr "" -#: ../source/key_projects.rst:446 +#: ../source/key_projects.rst:445 msgid "" ":gh:`Source ` | :gh:`Issues ` | `PyPI " "`__" msgstr "" -#: ../source/key_projects.rst:450 +#: ../source/key_projects.rst:449 msgid "" "Enscons is a Python packaging tool based on `SCons`_. It builds :ref:`pip`-" "compatible source distributions and wheels without using distutils or " @@ -8717,17 +8688,17 @@ msgid "" "independent of enscons." msgstr "" -#: ../source/key_projects.rst:465 +#: ../source/key_projects.rst:464 msgid "Hashdist" msgstr "" -#: ../source/key_projects.rst:467 +#: ../source/key_projects.rst:466 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:470 +#: ../source/key_projects.rst:469 msgid "" "Hashdist is a library for building non-root software distributions. Hashdist " "is trying to be “the Debian of choice for cases where Debian technology " @@ -8738,34 +8709,34 @@ msgid "" "researchers but has been lacking in maintenance since 2016." msgstr "" -#: ../source/key_projects.rst:482 +#: ../source/key_projects.rst:481 msgid "Maturin" msgstr "" -#: ../source/key_projects.rst:484 +#: ../source/key_projects.rst:483 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:487 +#: ../source/key_projects.rst:486 msgid "" "Maturin is a build backend for Rust extension modules, also written in Rust. " "It supports building wheels for python 3.7+ on Windows, Linux, macOS and " "FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." msgstr "" -#: ../source/key_projects.rst:495 +#: ../source/key_projects.rst:494 msgid "meson-python" msgstr "" -#: ../source/key_projects.rst:497 +#: ../source/key_projects.rst:496 msgid "" "`Docs `__ | `GitHub `__" msgstr "" -#: ../source/key_projects.rst:500 +#: ../source/key_projects.rst:499 msgid "" "``meson-python`` is a build backend that uses the Meson_ build system. It " "enables Python package authors to use Meson_ as the build system for their " @@ -8773,44 +8744,44 @@ msgid "" "to fill the needs of most complex build configurations." msgstr "" -#: ../source/key_projects.rst:510 +#: ../source/key_projects.rst:509 msgid "multibuild" msgstr "" -#: ../source/key_projects.rst:512 +#: ../source/key_projects.rst:511 msgid "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:514 +#: ../source/key_projects.rst:513 msgid "" "Multibuild is a set of CI scripts for building and testing Python :term:" "`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :" "ref:`cibuildwheel`." msgstr "" -#: ../source/key_projects.rst:520 +#: ../source/key_projects.rst:519 msgid "pdm" msgstr "" -#: ../source/key_projects.rst:522 +#: ../source/key_projects.rst:521 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:526 +#: ../source/key_projects.rst:525 msgid "" "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " "store project metadata as defined in :pep:`621`." msgstr "" -#: ../source/key_projects.rst:534 +#: ../source/key_projects.rst:533 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:538 +#: ../source/key_projects.rst:537 msgid "" "pex is both a library and tool for generating :file:`.pex` (Python " "EXecutable) files, standalone Python environments in the spirit of :ref:" @@ -8819,18 +8790,18 @@ msgid "" "designed to make deployment of Python applications as simple as ``cp``." msgstr "" -#: ../source/key_projects.rst:547 +#: ../source/key_projects.rst:546 msgid "pip-tools" msgstr "" -#: ../source/key_projects.rst:549 +#: ../source/key_projects.rst:548 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:553 +#: ../source/key_projects.rst:552 msgid "" "pip-tools is a suite of tools meant for Python system administrators and " "release managers who particularly want to keep their builds deterministic " @@ -8841,17 +8812,17 @@ msgid "" "not provide), and create layers of constraints for the program to obey." msgstr "" -#: ../source/key_projects.rst:565 +#: ../source/key_projects.rst:564 msgid "piwheels" msgstr "" -#: ../source/key_projects.rst:567 +#: ../source/key_projects.rst:566 msgid "" "`Website `__ | :doc:`Docs ` | " "`GitHub `__" msgstr "" -#: ../source/key_projects.rst:571 +#: ../source/key_projects.rst:570 msgid "" "piwheels is a website, and software underpinning it, that fetches source " "code distribution packages from PyPI and compiles them into binary wheels " @@ -8859,17 +8830,17 @@ msgid "" "Pi OS pre-configures pip to use piwheels.org as an additional index to PyPI." msgstr "" -#: ../source/key_projects.rst:580 +#: ../source/key_projects.rst:579 msgid "poetry" msgstr "" -#: ../source/key_projects.rst:582 +#: ../source/key_projects.rst:581 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:586 +#: ../source/key_projects.rst:585 msgid "" "poetry is a command-line tool to handle dependency installation and " "isolation as well as building and packaging of Python packages. It uses " @@ -8879,17 +8850,17 @@ msgid "" "caching metadata about dependencies." msgstr "" -#: ../source/key_projects.rst:596 +#: ../source/key_projects.rst:595 msgid "pypiserver" msgstr "" -#: ../source/key_projects.rst:598 +#: ../source/key_projects.rst:597 msgid "" "`GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:601 +#: ../source/key_projects.rst:600 msgid "" "pypiserver is a minimalist application that serves as a private Python " "package index within organizations, implementing a simple API and browser " @@ -8899,17 +8870,17 @@ msgid "" "from pypiserver and from PyPI." msgstr "" -#: ../source/key_projects.rst:611 +#: ../source/key_projects.rst:610 msgid "PyScaffold" msgstr "" -#: ../source/key_projects.rst:613 +#: ../source/key_projects.rst:612 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:617 +#: ../source/key_projects.rst:616 msgid "" "PyScaffold is a project generator for bootstrapping Python packages, ready " "to be shared on PyPI and installable via :ref:`pip`. It relies on a set of " @@ -8919,18 +8890,18 @@ msgid "" "existing projects to make packaging easier." msgstr "" -#: ../source/key_projects.rst:629 +#: ../source/key_projects.rst:628 msgid "scikit-build" msgstr "" -#: ../source/key_projects.rst:631 +#: ../source/key_projects.rst:630 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:635 +#: ../source/key_projects.rst:634 msgid "" "Scikit-build is a :ref:`setuptools` wrapper for CPython that builds C/C++/" "Fortran/Cython extensions It uses `cmake `__ " @@ -8941,18 +8912,18 @@ msgid "" "ninja>`__ (also available on PyPI)." msgstr "" -#: ../source/key_projects.rst:646 +#: ../source/key_projects.rst:645 msgid "scikit-build-core" msgstr "" -#: ../source/key_projects.rst:648 +#: ../source/key_projects.rst:647 msgid "" "`Docs `__ | `GitHub " "`__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:652 +#: ../source/key_projects.rst:651 msgid "" "Scikit-build-core is a build backend for CPython C/C++/Fortran/Cython " "extensions. It enables users to write extensions with `cmake `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:668 +#: ../source/key_projects.rst:667 msgid "" "shiv is a command line utility for building fully self contained Python " "zipapps as outlined in :pep:`441`, but with all their dependencies included. " @@ -8980,7 +8951,7 @@ msgid "" "tools fast & easy." msgstr "" -#: ../source/key_projects.rst:678 +#: ../source/key_projects.rst:677 msgid "" ":doc:`Docs ` | `GitHub `__ | " "`Paper `__" msgstr "" -#: ../source/key_projects.rst:683 +#: ../source/key_projects.rst:682 msgid "" "A flexible package manager designed to support multiple versions, " "configurations, platforms, and compilers. Spack is like Homebrew, but " @@ -8999,24 +8970,24 @@ msgid "" "supercomputers." msgstr "" -#: ../source/key_projects.rst:691 +#: ../source/key_projects.rst:690 msgid "" "Spack is not in PyPI (yet), but it requires no installation and can be used " "immediately after cloning from GitHub." msgstr "" -#: ../source/key_projects.rst:697 +#: ../source/key_projects.rst:696 msgid "zest.releaser" msgstr "" -#: ../source/key_projects.rst:699 +#: ../source/key_projects.rst:698 msgid "" "`Docs `__ | `GitHub `__ | `PyPI `__" msgstr "" -#: ../source/key_projects.rst:703 +#: ../source/key_projects.rst:702 msgid "" "``zest.releaser`` is a Python package release tool providing an abstraction " "layer on top of :ref:`twine`. Python developers use ``zest.releaser`` to " @@ -9024,21 +8995,21 @@ msgid "" "releases in source control, and uploading new packages to PyPI." msgstr "" -#: ../source/key_projects.rst:710 +#: ../source/key_projects.rst:709 msgid "Standard Library Projects" msgstr "" -#: ../source/key_projects.rst:715 +#: ../source/key_projects.rst:714 msgid "ensurepip" msgstr "" -#: ../source/key_projects.rst:717 +#: ../source/key_projects.rst:716 msgid "" "`Docs `__ | `Issues " "`__" msgstr "" -#: ../source/key_projects.rst:720 +#: ../source/key_projects.rst:719 msgid "" "A package in the Python Standard Library that provides support for " "bootstrapping :ref:`pip` into an existing Python installation or virtual " @@ -9046,17 +9017,17 @@ msgid "" "will be used during the build of the Python distribution." msgstr "" -#: ../source/key_projects.rst:729 +#: ../source/key_projects.rst:728 msgid "venv" msgstr "" -#: ../source/key_projects.rst:731 +#: ../source/key_projects.rst:730 msgid "" "`Docs `__ | `Issues `__" msgstr "" -#: ../source/key_projects.rst:734 +#: ../source/key_projects.rst:733 msgid "" "A package in the Python Standard Library (starting with Python 3.3) for " "creating :term:`Virtual Environments `. For more " @@ -10430,25 +10401,17 @@ msgid "" "for using one of the most balanced, flexible languages available." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:6 +#: ../source/specifications/binary-distribution-format.rst:7 msgid "Binary distribution format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:8 +#: ../source/specifications/binary-distribution-format.rst:9 msgid "" -"The binary distribution format (:term:`wheel `) was originally " -"defined in :pep:`427`. The current version of the specification is here." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:13 -msgid "Abstract" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:15 -msgid "This PEP describes a built-package format for Python called \"wheel\"." +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:17 +#: ../source/specifications/binary-distribution-format.rst:12 msgid "" "A wheel is a ZIP-format archive with a specially formatted file name and the " "``.whl`` extension. It contains a single distribution nearly as it would be " @@ -10459,86 +10422,53 @@ msgid "" "their final paths at any later time." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:27 -msgid "PEP Acceptance" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:29 -msgid "" -"This PEP was accepted, and the defined wheel version updated to 1.0, by Nick " -"Coghlan on 16th February, 2013 [1]_" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:34 -msgid "Rationale" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:36 -msgid "" -"Python needs a package format that is easier to install than sdist. Python's " -"sdist packages are defined by and require the distutils and setuptools build " -"systems, running arbitrary code to build-and-install, and re-compile, code " -"just so it can be installed into a new virtualenv. This system of " -"conflating build-install is slow, hard to maintain, and hinders innovation " -"in both build systems and installers." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:43 -msgid "" -"Wheel attempts to remedy these problems by providing a simpler interface " -"between the build system and the installer. The wheel binary package format " -"frees installers from having to know about the build system, saves time by " -"amortizing compile time over many installations, and removes the need to " -"install a build system in the target environment." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:52 +#: ../source/specifications/binary-distribution-format.rst:22 #: ../source/specifications/platform-compatibility-tags.rst:46 msgid "Details" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:55 +#: ../source/specifications/binary-distribution-format.rst:25 msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:57 +#: ../source/specifications/binary-distribution-format.rst:27 msgid "Wheel installation notionally consists of two phases:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:59 +#: ../source/specifications/binary-distribution-format.rst:29 msgid "Unpack." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:61 +#: ../source/specifications/binary-distribution-format.rst:31 msgid "Parse ``distribution-1.0.dist-info/WHEEL``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:62 +#: ../source/specifications/binary-distribution-format.rst:32 msgid "" "Check that installer is compatible with Wheel-Version. Warn if minor " "version is greater, abort if major version is greater." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:64 +#: ../source/specifications/binary-distribution-format.rst:34 msgid "" "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:66 +#: ../source/specifications/binary-distribution-format.rst:36 msgid "Else unpack archive into platlib (site-packages)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:68 +#: ../source/specifications/binary-distribution-format.rst:38 msgid "Spread." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:70 +#: ../source/specifications/binary-distribution-format.rst:40 msgid "" "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " "data) ``distribution-1.0.data/``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:72 +#: ../source/specifications/binary-distribution-format.rst:42 msgid "" "Move each subtree of ``distribution-1.0.data/`` onto its destination path. " "Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " @@ -10547,35 +10477,35 @@ msgid "" "``distutils.command.install``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:78 +#: ../source/specifications/binary-distribution-format.rst:48 msgid "" "If applicable, update scripts starting with ``#!python`` to point to the " "correct interpreter." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:80 +#: ../source/specifications/binary-distribution-format.rst:50 msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:82 +#: ../source/specifications/binary-distribution-format.rst:52 msgid "Remove empty ``distribution-1.0.data`` directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:83 +#: ../source/specifications/binary-distribution-format.rst:53 msgid "" "Compile any installed .py to .pyc. (Uninstallers should be smart enough to " "remove .pyc even if it is not mentioned in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:87 +#: ../source/specifications/binary-distribution-format.rst:57 msgid "Recommended installer features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:97 +#: ../source/specifications/binary-distribution-format.rst:67 msgid "Rewrite ``#!python``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:90 +#: ../source/specifications/binary-distribution-format.rst:60 msgid "" "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" "``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" @@ -10583,32 +10513,32 @@ msgid "" "need to add the +x bit to these files if the archive was created on Windows." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:96 +#: ../source/specifications/binary-distribution-format.rst:66 msgid "" "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " "script instead of a console script." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:102 +#: ../source/specifications/binary-distribution-format.rst:72 msgid "Generate script wrappers." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:100 +#: ../source/specifications/binary-distribution-format.rst:70 msgid "" "In wheel, scripts packaged on Unix systems will certainly not have " "accompanying .exe wrappers. Windows installers may want to add them during " "install." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:105 +#: ../source/specifications/binary-distribution-format.rst:75 msgid "Recommended archiver features" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:112 +#: ../source/specifications/binary-distribution-format.rst:82 msgid "Place ``.dist-info`` at the end of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:108 +#: ../source/specifications/binary-distribution-format.rst:78 msgid "" "Archivers are encouraged to place the ``.dist-info`` files physically at the " "end of the archive. This enables some potentially interesting ZIP tricks " @@ -10616,41 +10546,41 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:115 +#: ../source/specifications/binary-distribution-format.rst:85 msgid "File Format" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:118 +#: ../source/specifications/binary-distribution-format.rst:88 msgid "File name convention" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:120 +#: ../source/specifications/binary-distribution-format.rst:90 msgid "" "The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" "{abi tag}-{platform tag}.whl``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "distribution" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:124 +#: ../source/specifications/binary-distribution-format.rst:94 msgid "Distribution name, e.g. 'django', 'pyramid'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "version" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:127 +#: ../source/specifications/binary-distribution-format.rst:97 msgid "Distribution version, e.g. 1.0." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:152 +#: ../source/specifications/binary-distribution-format.rst:122 msgid "build tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/binary-distribution-format.rst:100 msgid "" "Optional build number. Must start with a digit. Acts as a tie-breaker if " "two wheel file names are the same in all other respects (i.e. name, version, " @@ -10659,14 +10589,14 @@ msgid "" "the second item being the remainder of the tag as a ``str``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:137 +#: ../source/specifications/binary-distribution-format.rst:107 msgid "" "A common use-case for build numbers is rebuilding a binary distribution due " "to a change in the build environment, like when using the manylinux image to " "build distributions using pre-release CPython versions." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:144 +#: ../source/specifications/binary-distribution-format.rst:114 msgid "" "Build numbers are not a part of the distribution version and thus are " "difficult to reference externally, especially so outside the Python " @@ -10674,7 +10604,7 @@ msgid "" "need to referenced externally is when resolving a security vulnerability." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:149 +#: ../source/specifications/binary-distribution-format.rst:119 msgid "" "Due to this limitation, new distributions which need to be referenced " "externally **should not** use build numbers when building the new " @@ -10682,33 +10612,33 @@ msgid "" "such cases." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "language implementation and version tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:155 +#: ../source/specifications/binary-distribution-format.rst:125 msgid "E.g. 'py27', 'py2', 'py3'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 #: ../source/specifications/platform-compatibility-tags.rst:27 msgid "abi tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:158 +#: ../source/specifications/binary-distribution-format.rst:128 msgid "E.g. 'cp33m', 'abi3', 'none'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 #: ../source/specifications/platform-compatibility-tags.rst:30 msgid "platform tag" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:161 +#: ../source/specifications/binary-distribution-format.rst:131 msgid "E.g. 'linux_x86_64', 'any'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:163 +#: ../source/specifications/binary-distribution-format.rst:133 msgid "" "For example, ``distribution-1.0-1-py27-none-any.whl`` is the first build of " "a package called 'distribution', and is compatible with Python 2.7 (any " @@ -10716,25 +10646,25 @@ msgid "" "architecture." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:168 +#: ../source/specifications/binary-distribution-format.rst:138 msgid "" "The last three components of the filename before the extension are called " "\"compatibility tags.\" The compatibility tags express the package's basic " "interpreter requirements and are detailed in PEP 425." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:173 +#: ../source/specifications/binary-distribution-format.rst:143 msgid "Escaping and Unicode" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:175 +#: ../source/specifications/binary-distribution-format.rst:145 msgid "" "As the components of the filename are separated by a dash (``-``, HYPHEN-" "MINUS), this character cannot appear within any component. This is handled " "as follows:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:178 +#: ../source/specifications/binary-distribution-format.rst:148 msgid "" "In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE " "and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase " @@ -10745,63 +10675,63 @@ msgid "" "these were allowed by an earlier version of this specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:185 +#: ../source/specifications/binary-distribution-format.rst:155 msgid "" "Version numbers should be normalised according to the :ref:`Version " "specifier specification `. Normalised version numbers " "cannot contain ``-``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:187 +#: ../source/specifications/binary-distribution-format.rst:157 msgid "" "The remaining components may not contain ``-`` characters, so no escaping is " "necessary." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:190 +#: ../source/specifications/binary-distribution-format.rst:160 msgid "" "Tools producing wheels should verify that the filename components do not " "contain ``-``, as the resulting file may not be processed correctly if they " "do." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:193 +#: ../source/specifications/binary-distribution-format.rst:163 msgid "" "The archive filename is Unicode. It will be some time before the tools are " "updated to support non-ASCII filenames, but they are supported in this " "specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:197 +#: ../source/specifications/binary-distribution-format.rst:167 msgid "" "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " "clients in common use do not properly display UTF-8 filenames, the encoding " "is supported by both the ZIP specification and Python's ``zipfile``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:203 +#: ../source/specifications/binary-distribution-format.rst:173 msgid "File contents" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:205 +#: ../source/specifications/binary-distribution-format.rst:175 msgid "" "The contents of a wheel file, where {distribution} is replaced with the name " "of the package, e.g. ``beaglevote`` and {version} is replaced with its " "version, e.g. ``1.0.0``, consist of:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:209 +#: ../source/specifications/binary-distribution-format.rst:179 msgid "" "``/``, the root of the archive, contains all files to be installed in " "``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " "``platlib`` are usually both ``site-packages``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:212 +#: ../source/specifications/binary-distribution-format.rst:182 msgid "``{distribution}-{version}.dist-info/`` contains metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:213 +#: ../source/specifications/binary-distribution-format.rst:183 msgid "" "``{distribution}-{version}.data/`` contains one subdirectory for each non-" "empty install scheme key not already covered, where the subdirectory name is " @@ -10809,71 +10739,71 @@ msgid "" "``headers``, ``purelib``, ``platlib``)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:217 +#: ../source/specifications/binary-distribution-format.rst:187 msgid "" "Python scripts must appear in ``scripts`` and begin with exactly ``b'#!" "python'`` in order to enjoy script wrapper generation and ``#!python`` " "rewriting at install time. They may have any or no extension." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:221 +#: ../source/specifications/binary-distribution-format.rst:191 msgid "" "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " "greater format metadata." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:223 +#: ../source/specifications/binary-distribution-format.rst:193 msgid "" "``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " "itself in the same basic key: value format::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:233 +#: ../source/specifications/binary-distribution-format.rst:203 msgid "``Wheel-Version`` is the version number of the Wheel specification." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:234 +#: ../source/specifications/binary-distribution-format.rst:204 msgid "" "``Generator`` is the name and optionally the version of the software that " "produced the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:236 +#: ../source/specifications/binary-distribution-format.rst:206 msgid "" "``Root-Is-Purelib`` is true if the top level directory of the archive should " "be installed into purelib; otherwise the root should be installed into " "platlib." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:239 +#: ../source/specifications/binary-distribution-format.rst:209 msgid "" "``Tag`` is the wheel's expanded compatibility tags; in the example the " "filename would contain ``py2.py3-none-any``." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:241 +#: ../source/specifications/binary-distribution-format.rst:211 msgid "" "``Build`` is the build number and is omitted if there is no build number." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:242 +#: ../source/specifications/binary-distribution-format.rst:212 msgid "" "A wheel installer should warn if Wheel-Version is greater than the version " "it supports, and must fail if Wheel-Version has a greater major version than " "the version it supports." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:245 +#: ../source/specifications/binary-distribution-format.rst:215 msgid "" "Wheel, being an installation format that is intended to work across multiple " "versions of Python, does not generally include .pyc files." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:247 +#: ../source/specifications/binary-distribution-format.rst:217 msgid "Wheel does not contain setup.py or setup.cfg." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:249 +#: ../source/specifications/binary-distribution-format.rst:219 msgid "" "This version of the wheel specification is based on the distutils install " "schemes and does not define how to install files to other locations. The " @@ -10881,28 +10811,28 @@ msgid "" "wininst and egg binary formats." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:256 -#: ../source/specifications/recording-installed-packages.rst:37 +#: ../source/specifications/binary-distribution-format.rst:226 +#: ../source/specifications/recording-installed-packages.rst:39 msgid "The .dist-info directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:258 +#: ../source/specifications/binary-distribution-format.rst:228 msgid "" "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:260 +#: ../source/specifications/binary-distribution-format.rst:230 msgid "" "METADATA is the package metadata, the same format as PKG-INFO as found at " "the root of sdists." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:262 +#: ../source/specifications/binary-distribution-format.rst:232 msgid "WHEEL is the wheel metadata specific to a build of the package." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:263 +#: ../source/specifications/binary-distribution-format.rst:233 msgid "" "RECORD is a list of (almost) all the files in the wheel and their secure " "hashes. Unlike PEP 376, every file except RECORD, which cannot contain a " @@ -10911,22 +10841,22 @@ msgid "" "rely on the strong hashes in RECORD to validate the integrity of the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:269 +#: ../source/specifications/binary-distribution-format.rst:239 msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:270 +#: ../source/specifications/binary-distribution-format.rst:240 msgid "" "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:272 +#: ../source/specifications/binary-distribution-format.rst:242 msgid "" "RECORD.p7s is allowed as a courtesy to anyone who would prefer to use S/MIME " "signatures to secure their wheel files. It is not mentioned in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:275 +#: ../source/specifications/binary-distribution-format.rst:245 msgid "" "During extraction, wheel installers verify all the hashes in RECORD against " "the file contents. Apart from RECORD and its signatures, installation will " @@ -10934,29 +10864,29 @@ msgid "" "in RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:282 +#: ../source/specifications/binary-distribution-format.rst:252 msgid "The .data directory" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:284 +#: ../source/specifications/binary-distribution-format.rst:254 msgid "" "Any file that is not normally installed inside site-packages goes into the ." "data directory, named as the .dist-info directory but with the .data/ " "extension::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:292 +#: ../source/specifications/binary-distribution-format.rst:262 msgid "" "The .data directory contains subdirectories with the scripts, headers, " "documentation and so forth from the distribution. During installation the " "contents of these subdirectories are moved onto their destination paths." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:298 +#: ../source/specifications/binary-distribution-format.rst:268 msgid "Signed wheel files" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:300 +#: ../source/specifications/binary-distribution-format.rst:270 msgid "" "Wheel files include an extended RECORD that enables digital signatures. PEP " "376's RECORD is altered to include a secure hash " @@ -10966,7 +10896,7 @@ msgid "" "files, but not RECORD which cannot contain its own hash. For example::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:311 +#: ../source/specifications/binary-distribution-format.rst:281 msgid "" "The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in RECORD " "at all since they can only be added after RECORD is generated. Every other " @@ -10974,25 +10904,25 @@ msgid "" "will fail." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:316 +#: ../source/specifications/binary-distribution-format.rst:286 msgid "" "If JSON web signatures are used, one or more JSON Web Signature JSON " "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent to " "RECORD. JWS is used to sign RECORD by including the SHA-256 hash of RECORD " -"as the signature's JSON payload::" +"as the signature's JSON payload:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:323 +#: ../source/specifications/binary-distribution-format.rst:295 msgid "(The hash value is the same format used in RECORD.)" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:325 +#: ../source/specifications/binary-distribution-format.rst:297 msgid "" "If RECORD.p7s is used, it must contain a detached S/MIME format signature of " "RECORD." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:328 +#: ../source/specifications/binary-distribution-format.rst:300 msgid "" "A wheel installer is not required to understand digital signatures but MUST " "verify the hashes in RECORD against the extracted file contents. When the " @@ -11000,87 +10930,41 @@ msgid "" "only needs to establish that RECORD matches the signature." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:333 +#: ../source/specifications/binary-distribution-format.rst:305 msgid "See" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:335 +#: ../source/specifications/binary-distribution-format.rst:307 msgid "https://datatracker.ietf.org/doc/html/rfc7515" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:336 +#: ../source/specifications/binary-distribution-format.rst:308 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" "serialization-01" msgstr "http://self-issued.info/docs/draft-jones-jose-json-private-key.html" -#: ../source/specifications/binary-distribution-format.rst:337 +#: ../source/specifications/binary-distribution-format.rst:309 msgid "https://datatracker.ietf.org/doc/html/rfc7517" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:338 +#: ../source/specifications/binary-distribution-format.rst:310 #, fuzzy msgid "" "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" msgstr "http://self-issued.info/docs/draft-jones-jose-json-private-key.html" -#: ../source/specifications/binary-distribution-format.rst:342 -msgid "Comparison to .egg" -msgstr "與 .egg 的比較" +#: ../source/specifications/binary-distribution-format.rst:314 +#: ../source/specifications/platform-compatibility-tags.rst:244 +msgid "FAQ" +msgstr "" -#: ../source/specifications/binary-distribution-format.rst:344 -msgid "" -"Wheel is an installation format; egg is importable. Wheel archives do not " -"need to include .pyc and are less tied to a specific Python version or " -"implementation. Wheel can install (pure Python) packages built with previous " -"versions of Python so you don't always have to wait for the packager to " -"catch up." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:349 -msgid "" -"Wheel uses .dist-info directories; egg uses .egg-info. Wheel is compatible " -"with the new world of Python packaging and the new concepts it brings." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:352 -msgid "" -"Wheel has a richer file naming convention for today's multi-implementation " -"world. A single wheel archive can indicate its compatibility with a number " -"of Python language versions and implementations, ABIs, and system " -"architectures. Historically the ABI has been specific to a CPython release, " -"wheel is ready for the stable ABI." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:358 -msgid "" -"Wheel is lossless. The first wheel implementation bdist_wheel always " -"generates egg-info, and then converts it to a .whl. It is also possible to " -"convert existing eggs and bdist_wininst distributions." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:362 -msgid "" -"Wheel is versioned. Every wheel file contains the version of the wheel " -"specification and the implementation that packaged it. Hopefully the next " -"migration can simply be to Wheel 2.0." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:365 -msgid "Wheel is a reference to the other Python." -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:369 -#: ../source/specifications/platform-compatibility-tags.rst:244 -msgid "FAQ" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:373 +#: ../source/specifications/binary-distribution-format.rst:318 msgid "Wheel defines a .data directory. Should I put all my data there?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:375 +#: ../source/specifications/binary-distribution-format.rst:320 msgid "" "This specification does not have an opinion on how you should organize your " "code. The .data directory is just a place for any files that are not " @@ -11090,11 +10974,11 @@ msgid "" "directory." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:384 +#: ../source/specifications/binary-distribution-format.rst:329 msgid "Why does wheel include attached signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:386 +#: ../source/specifications/binary-distribution-format.rst:331 msgid "" "Attached signatures are more convenient than detached signatures because " "they travel with the archive. Since only the individual files are signed, " @@ -11103,38 +10987,38 @@ msgid "" "archive." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:394 +#: ../source/specifications/binary-distribution-format.rst:339 msgid "Why does wheel allow JWS signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:396 +#: ../source/specifications/binary-distribution-format.rst:341 msgid "" "The JOSE specifications of which JWS is a part are designed to be easy to " "implement, a feature that is also one of wheel's primary design goals. JWS " "yields a useful, concise pure-Python implementation." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:402 +#: ../source/specifications/binary-distribution-format.rst:347 msgid "Why does wheel also allow S/MIME signatures?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:404 +#: ../source/specifications/binary-distribution-format.rst:349 msgid "" "S/MIME signatures are allowed for users who need or want to use existing " "public key infrastructure with wheel." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:407 +#: ../source/specifications/binary-distribution-format.rst:352 msgid "" "Signed packages are only a basic building block in a secure package update " "system. Wheel only provides the building block." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:412 +#: ../source/specifications/binary-distribution-format.rst:357 msgid "What's the deal with \"purelib\" vs. \"platlib\"?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:414 +#: ../source/specifications/binary-distribution-format.rst:359 msgid "" "Wheel preserves the \"purelib\" vs. \"platlib\" distinction, which is " "significant on some platforms. For example, Fedora installs pure Python " @@ -11142,7 +11026,7 @@ msgid "" "packages to '/usr/lib64/pythonX.Y/site-packages'." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/binary-distribution-format.rst:364 msgid "" "A wheel with \"Root-Is-Purelib: false\" with all its files in ``{name}-" "{version}.data/purelib`` is equivalent to a wheel with \"Root-Is-Purelib: " @@ -11150,18 +11034,18 @@ msgid "" "both the \"purelib\" and \"platlib\" categories." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:424 +#: ../source/specifications/binary-distribution-format.rst:369 msgid "" "In practice a wheel should have only one of \"purelib\" or \"platlib\" " "depending on whether it is pure Python or not and those files should be at " "the root with the appropriate setting given for \"Root-is-purelib\"." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:432 +#: ../source/specifications/binary-distribution-format.rst:377 msgid "Is it possible to import Python code directly from a wheel file?" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:434 +#: ../source/specifications/binary-distribution-format.rst:379 msgid "" "Technically, due to the combination of supporting installation via simple " "extraction and using an archive format that is compatible with " @@ -11170,7 +11054,7 @@ msgid "" "format design, actually relying on it is generally discouraged." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:440 +#: ../source/specifications/binary-distribution-format.rst:385 msgid "" "Firstly, wheel *is* designed primarily as a distribution format, so skipping " "the installation step also means deliberately avoiding any reliance on " @@ -11181,7 +11065,7 @@ msgid "" "extensions by publishing header files in the appropriate place)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:449 +#: ../source/specifications/binary-distribution-format.rst:394 msgid "" "Secondly, while some Python software is written to support running directly " "from a zip archive, it is still common for code to be written assuming it " @@ -11199,7 +11083,7 @@ msgid "" "components may still require the availability of an actual on-disk file." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:466 +#: ../source/specifications/binary-distribution-format.rst:411 msgid "" "Like metaclasses, monkeypatching and metapath importers, if you're not " "already sure you need to take advantage of this feature, you almost " @@ -11208,70 +11092,67 @@ msgid "" "package before accepting it as a genuine bug." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:473 -msgid "Changes" +#: ../source/specifications/binary-distribution-format.rst:419 +#: ../source/specifications/direct-url-data-structure.rst:266 +#: ../source/specifications/direct-url.rst:66 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/inline-script-metadata.rst:239 +#: ../source/specifications/name-normalization.rst:42 +#: ../source/specifications/pyproject-toml.rst:442 +#: ../source/specifications/source-distribution-format.rst:144 +#: ../source/specifications/version-specifiers.rst:1262 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:421 +msgid "This specification was originally approved as :pep:`427`." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:475 -msgid "Since :pep:`427`, this specification has changed as follows:" +#: ../source/specifications/binary-distribution-format.rst:423 +msgid "The following changes were applied since the initial version:" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:477 +#: ../source/specifications/binary-distribution-format.rst:425 msgid "" "The rules on escaping in wheel filenames were revised, to bring them into " "line with what popular tools actually do (February 2021)." msgstr "" -#: ../source/specifications/binary-distribution-format.rst:484 -msgid "" -"PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" -"February/124103.html)" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:489 +#: ../source/specifications/binary-distribution-format.rst:430 msgid "Appendix" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:491 +#: ../source/specifications/binary-distribution-format.rst:432 msgid "Example urlsafe-base64-nopad implementation::" msgstr "" -#: ../source/specifications/binary-distribution-format.rst:505 -#: ../source/specifications/externally-managed-environments.rst:464 -msgid "Copyright" -msgstr "" - -#: ../source/specifications/binary-distribution-format.rst:507 -msgid "This document has been placed into the public domain." -msgstr "" - -#: ../source/specifications/core-metadata.rst:5 +#: ../source/specifications/core-metadata.rst:7 msgid "Core metadata specifications" msgstr "" -#: ../source/specifications/core-metadata.rst:7 +#: ../source/specifications/core-metadata.rst:9 msgid "" "Fields defined in the following specification should be considered valid, " "complete and not subject to change. The required fields are:" msgstr "" -#: ../source/specifications/core-metadata.rst:10 +#: ../source/specifications/core-metadata.rst:12 msgid "``Metadata-Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:11 +#: ../source/specifications/core-metadata.rst:13 msgid "``Name``" msgstr "" -#: ../source/specifications/core-metadata.rst:12 +#: ../source/specifications/core-metadata.rst:14 msgid "``Version``" msgstr "" -#: ../source/specifications/core-metadata.rst:14 +#: ../source/specifications/core-metadata.rst:16 msgid "All the other fields are optional." msgstr "" -#: ../source/specifications/core-metadata.rst:16 +#: ../source/specifications/core-metadata.rst:18 msgid "" "The standard file format for metadata (including in :doc:`wheels ` and :doc:`installed projects `, the major version is the value before the first dot)." msgstr "" -#: ../source/specifications/core-metadata.rst:58 +#: ../source/specifications/core-metadata.rst:60 msgid "" "For broader compatibility, build tools MAY choose to produce distribution " "metadata using the lowest metadata version that includes all of the needed " "fields." msgstr "" -#: ../source/specifications/core-metadata.rst:62 -#: ../source/specifications/core-metadata.rst:84 -#: ../source/specifications/core-metadata.rst:101 -#: ../source/specifications/core-metadata.rst:166 -#: ../source/specifications/core-metadata.rst:181 -#: ../source/specifications/core-metadata.rst:219 -#: ../source/specifications/core-metadata.rst:291 -#: ../source/specifications/core-metadata.rst:295 -#: ../source/specifications/core-metadata.rst:299 -#: ../source/specifications/core-metadata.rst:303 -#: ../source/specifications/core-metadata.rst:335 -#: ../source/specifications/core-metadata.rst:356 -#: ../source/specifications/core-metadata.rst:383 -#: ../source/specifications/core-metadata.rst:401 -#: ../source/specifications/core-metadata.rst:426 -#: ../source/specifications/core-metadata.rst:448 -#: ../source/specifications/core-metadata.rst:611 -#: ../source/specifications/core-metadata.rst:642 -#: ../source/specifications/core-metadata.rst:652 -#: ../source/specifications/core-metadata.rst:844 +#: ../source/specifications/core-metadata.rst:64 +#: ../source/specifications/core-metadata.rst:86 +#: ../source/specifications/core-metadata.rst:103 +#: ../source/specifications/core-metadata.rst:168 +#: ../source/specifications/core-metadata.rst:183 +#: ../source/specifications/core-metadata.rst:221 +#: ../source/specifications/core-metadata.rst:293 +#: ../source/specifications/core-metadata.rst:297 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:337 +#: ../source/specifications/core-metadata.rst:358 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:403 +#: ../source/specifications/core-metadata.rst:428 +#: ../source/specifications/core-metadata.rst:450 +#: ../source/specifications/core-metadata.rst:613 +#: ../source/specifications/core-metadata.rst:644 +#: ../source/specifications/core-metadata.rst:654 +#: ../source/specifications/core-metadata.rst:846 msgid "Example::" msgstr "" -#: ../source/specifications/core-metadata.rst:70 +#: ../source/specifications/core-metadata.rst:72 msgid "Name" msgstr "" -#: ../source/specifications/core-metadata.rst:73 +#: ../source/specifications/core-metadata.rst:75 msgid "Added additional restrictions on format from :pep:`508`" msgstr "" -#: ../source/specifications/core-metadata.rst:76 +#: ../source/specifications/core-metadata.rst:78 msgid "" "The name of the distribution. The name field is the primary identifier for a " "distribution. A valid name consists only of ASCII letters and numbers, " @@ -11373,41 +11254,41 @@ msgid "" "regex (run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/core-metadata.rst:88 +#: ../source/specifications/core-metadata.rst:90 msgid "" "For comparison purposes, the names should be :ref:`normalized ` before comparing." msgstr "" -#: ../source/specifications/core-metadata.rst:93 +#: ../source/specifications/core-metadata.rst:95 msgid "Version" msgstr "" -#: ../source/specifications/core-metadata.rst:97 +#: ../source/specifications/core-metadata.rst:99 msgid "" "A string containing the distribution's version number. This field must be " "in the format specified in the :ref:`Version specifier specification " "`." msgstr "" -#: ../source/specifications/core-metadata.rst:109 +#: ../source/specifications/core-metadata.rst:111 msgid "Dynamic (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:113 +#: ../source/specifications/core-metadata.rst:115 msgid "" "A string containing the name of another core metadata field. The field names " "``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " "field." msgstr "" -#: ../source/specifications/core-metadata.rst:117 +#: ../source/specifications/core-metadata.rst:119 msgid "" "When found in the metadata of a source distribution, the following rules " "apply:" msgstr "" -#: ../source/specifications/core-metadata.rst:120 +#: ../source/specifications/core-metadata.rst:122 msgid "" "If a field is *not* marked as ``Dynamic``, then the value of the field in " "any wheel built from the sdist MUST match the value in the sdist. If the " @@ -11415,20 +11296,20 @@ msgid "" "be present in the wheel." msgstr "" -#: ../source/specifications/core-metadata.rst:124 +#: ../source/specifications/core-metadata.rst:126 msgid "" "If a field is marked as ``Dynamic``, it may contain any valid value in a " "wheel built from the sdist (including not being present at all)." msgstr "" -#: ../source/specifications/core-metadata.rst:127 +#: ../source/specifications/core-metadata.rst:129 msgid "" "If the sdist metadata version is older than version 2.2, then all fields " "should be treated as if they were specified with ``Dynamic`` (i.e. there are " "no special restrictions on the metadata of wheels built from the sdist)." msgstr "" -#: ../source/specifications/core-metadata.rst:131 +#: ../source/specifications/core-metadata.rst:133 msgid "" "In any context other than a source distribution, ``Dynamic`` is for " "information only, and indicates that the field value was calculated at wheel " @@ -11436,27 +11317,39 @@ msgid "" "wheels for the project." msgstr "" -#: ../source/specifications/core-metadata.rst:136 +#: ../source/specifications/core-metadata.rst:138 msgid "" "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." msgstr "" -#: ../source/specifications/core-metadata.rst:141 +#: ../source/specifications/core-metadata.rst:143 msgid "Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:145 +#: ../source/specifications/core-metadata.rst:147 msgid "" "A Platform specification describing an operating system supported by the " "distribution which is not listed in the \"Operating System\" Trove " "classifiers. See \"Classifier\" below." msgstr "" -#: ../source/specifications/core-metadata.rst:157 +#: ../source/specifications/core-metadata.rst:151 +#: ../source/specifications/core-metadata.rst:475 +#: ../source/specifications/core-metadata.rst:499 +#: ../source/specifications/core-metadata.rst:540 +#: ../source/specifications/core-metadata.rst:596 +#: ../source/specifications/core-metadata.rst:729 +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:800 +#: ../source/specifications/core-metadata.rst:822 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 msgid "Supported-Platform (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:161 +#: ../source/specifications/core-metadata.rst:163 msgid "" "Binary distributions containing a PKG-INFO file will use the Supported-" "Platform field in their metadata to specify the OS and CPU for which the " @@ -11464,19 +11357,19 @@ msgid "" "field are not specified in this PEP." msgstr "" -#: ../source/specifications/core-metadata.rst:175 +#: ../source/specifications/core-metadata.rst:177 msgid "Summary" msgstr "" -#: ../source/specifications/core-metadata.rst:179 +#: ../source/specifications/core-metadata.rst:181 msgid "A one-line summary of what the distribution does." msgstr "" -#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:201 msgid "This field may be specified in the message body instead." msgstr "" -#: ../source/specifications/core-metadata.rst:202 +#: ../source/specifications/core-metadata.rst:204 msgid "" "A longer description of the distribution that can run to several " "paragraphs. Software that deals with metadata should not assume any maximum " @@ -11484,7 +11377,7 @@ msgid "" "manual as the description." msgstr "" -#: ../source/specifications/core-metadata.rst:207 +#: ../source/specifications/core-metadata.rst:209 msgid "" "The contents of this field can be written using reStructuredText markup " "[1]_. For programs that work with the metadata, supporting markup is " @@ -11492,7 +11385,7 @@ msgid "" "means that authors should be conservative in the markup they use." msgstr "" -#: ../source/specifications/core-metadata.rst:213 +#: ../source/specifications/core-metadata.rst:215 msgid "" "To support empty lines and lines with indentation with respect to the RFC " "822 format, any CRLF character has to be suffixed by 7 spaces followed by a " @@ -11500,31 +11393,31 @@ msgid "" "folded field that can be interpreted by RFC822 parser [2]_." msgstr "" -#: ../source/specifications/core-metadata.rst:230 +#: ../source/specifications/core-metadata.rst:232 msgid "" "This encoding implies that any occurrences of a CRLF followed by 7 spaces " "and a pipe char have to be replaced by a single CRLF when the field is " "unfolded using a RFC822 reader." msgstr "" -#: ../source/specifications/core-metadata.rst:234 +#: ../source/specifications/core-metadata.rst:236 msgid "" "Alternatively, the distribution's description may instead be provided in the " "message body (i.e., after a completely blank line following the headers, " "with no indentation or other special formatting necessary)." msgstr "" -#: ../source/specifications/core-metadata.rst:243 +#: ../source/specifications/core-metadata.rst:245 msgid "Description-Content-Type" msgstr "" -#: ../source/specifications/core-metadata.rst:247 +#: ../source/specifications/core-metadata.rst:249 msgid "" "A string stating the markup syntax (if any) used in the distribution's " "description, so that tools can intelligently render the description." msgstr "" -#: ../source/specifications/core-metadata.rst:250 +#: ../source/specifications/core-metadata.rst:252 msgid "" "Historically, PyPI supported descriptions in plain text and " "`reStructuredText (reST) `" msgstr "" -#: ../source/specifications/core-metadata.rst:289 +#: ../source/specifications/core-metadata.rst:291 msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" msgstr "" -#: ../source/specifications/core-metadata.rst:307 +#: ../source/specifications/core-metadata.rst:309 msgid "" "If a ``Description-Content-Type`` is not specified, then applications should " "attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " "``text/plain`` if it is not valid rst." msgstr "" -#: ../source/specifications/core-metadata.rst:311 +#: ../source/specifications/core-metadata.rst:313 msgid "" "If a ``Description-Content-Type`` is an unrecognized value, then the assumed " "content type is ``text/plain`` (Although PyPI will probably reject anything " "with an unrecognized value)." msgstr "" -#: ../source/specifications/core-metadata.rst:315 +#: ../source/specifications/core-metadata.rst:317 msgid "" "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " "not specified or is set to an unrecognized value, then the assumed " "``variant`` is ``GFM``." msgstr "" -#: ../source/specifications/core-metadata.rst:319 +#: ../source/specifications/core-metadata.rst:321 msgid "" "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " "``variant`` defaults to ``GFM`` and thus it is equivalent to the example " "before it." msgstr "" -#: ../source/specifications/core-metadata.rst:328 +#: ../source/specifications/core-metadata.rst:330 msgid "Keywords" msgstr "" -#: ../source/specifications/core-metadata.rst:332 +#: ../source/specifications/core-metadata.rst:334 msgid "" "A list of additional keywords, separated by commas, to be used to assist " "searching for the distribution in a larger catalog." msgstr "" -#: ../source/specifications/core-metadata.rst:341 +#: ../source/specifications/core-metadata.rst:343 msgid "" "The specification previously showed keywords separated by spaces, but " "distutils and setuptools implemented it with commas. These tools have been " @@ -11638,91 +11531,91 @@ msgid "" "specification to match the de facto standard." msgstr "" -#: ../source/specifications/core-metadata.rst:350 +#: ../source/specifications/core-metadata.rst:352 msgid "Home-page" msgstr "" -#: ../source/specifications/core-metadata.rst:354 +#: ../source/specifications/core-metadata.rst:356 msgid "A string containing the URL for the distribution's home page." msgstr "" -#: ../source/specifications/core-metadata.rst:363 +#: ../source/specifications/core-metadata.rst:365 msgid "Download-URL" msgstr "" -#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:369 msgid "" "A string containing the URL from which this version of the distribution can " "be downloaded. (This means that the URL can't be something like \".../" "BeagleVote-latest.tgz\", but instead must be \".../BeagleVote-0.45.tgz\".)" msgstr "" -#: ../source/specifications/core-metadata.rst:376 +#: ../source/specifications/core-metadata.rst:378 msgid "Author" msgstr "" -#: ../source/specifications/core-metadata.rst:380 +#: ../source/specifications/core-metadata.rst:382 msgid "" "A string containing the author's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:395 msgid "Author-email" msgstr "" -#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:399 msgid "" "A string containing the author's e-mail address. It can contain a name and " "e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:405 -#: ../source/specifications/core-metadata.rst:452 +#: ../source/specifications/core-metadata.rst:407 +#: ../source/specifications/core-metadata.rst:454 msgid "" "Per RFC-822, this field may contain multiple comma-separated e-mail " "addresses::" msgstr "" -#: ../source/specifications/core-metadata.rst:415 +#: ../source/specifications/core-metadata.rst:417 msgid "Maintainer" msgstr "維護者" -#: ../source/specifications/core-metadata.rst:419 +#: ../source/specifications/core-metadata.rst:421 msgid "" "A string containing the maintainer's name at a minimum; additional contact " "information may be provided." msgstr "" -#: ../source/specifications/core-metadata.rst:422 +#: ../source/specifications/core-metadata.rst:424 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author``." msgstr "" -#: ../source/specifications/core-metadata.rst:436 +#: ../source/specifications/core-metadata.rst:438 msgid "Maintainer-email" msgstr "" -#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:442 msgid "" "A string containing the maintainer's e-mail address. It can contain a name " "and e-mail address in the legal forms for a RFC-822 ``From:`` header." msgstr "" -#: ../source/specifications/core-metadata.rst:444 +#: ../source/specifications/core-metadata.rst:446 msgid "" "Note that this field is intended for use when a project is being maintained " "by someone other than the original author: it should be omitted if it is " "identical to ``Author-email``." msgstr "" -#: ../source/specifications/core-metadata.rst:462 +#: ../source/specifications/core-metadata.rst:464 msgid "License" msgstr "" -#: ../source/specifications/core-metadata.rst:466 +#: ../source/specifications/core-metadata.rst:468 msgid "" "Text indicating the license covering the distribution where the license is " "not a selection from the \"License\" Trove classifiers. See :ref:" @@ -11732,11 +11625,11 @@ msgid "" "license." msgstr "" -#: ../source/specifications/core-metadata.rst:486 +#: ../source/specifications/core-metadata.rst:488 msgid "Classifier (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:490 +#: ../source/specifications/core-metadata.rst:492 msgid "" "Each entry is a string giving a single classification value for the " "distribution. Classifiers are described in :pep:`301`, and the Python " @@ -11744,43 +11637,43 @@ msgid "" "`__." msgstr "" -#: ../source/specifications/core-metadata.rst:495 -#: ../source/specifications/core-metadata.rst:585 -#: ../source/specifications/core-metadata.rst:725 -#: ../source/specifications/core-metadata.rst:750 +#: ../source/specifications/core-metadata.rst:497 +#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:727 +#: ../source/specifications/core-metadata.rst:752 msgid "This field may be followed by an environment marker after a semicolon." msgstr "" -#: ../source/specifications/core-metadata.rst:506 +#: ../source/specifications/core-metadata.rst:508 msgid "Requires-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:509 -#: ../source/specifications/core-metadata.rst:572 -#: ../source/specifications/core-metadata.rst:697 -#: ../source/specifications/core-metadata.rst:739 +#: ../source/specifications/core-metadata.rst:511 +#: ../source/specifications/core-metadata.rst:574 +#: ../source/specifications/core-metadata.rst:699 +#: ../source/specifications/core-metadata.rst:741 msgid "" "The field format specification was relaxed to accept the syntax used by " "popular publishing tools." msgstr "" -#: ../source/specifications/core-metadata.rst:513 +#: ../source/specifications/core-metadata.rst:515 msgid "" "Each entry contains a string naming some other distutils project required by " "this distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:516 +#: ../source/specifications/core-metadata.rst:518 msgid "The format of a requirement string contains from one to four parts:" msgstr "" -#: ../source/specifications/core-metadata.rst:518 +#: ../source/specifications/core-metadata.rst:520 msgid "" "A project name, in the same format as the ``Name:`` field. The only " "mandatory part." msgstr "" -#: ../source/specifications/core-metadata.rst:520 +#: ../source/specifications/core-metadata.rst:522 msgid "" "A comma-separated list of 'extra' names. These are defined by the required " "project, referring to specific features which may need extra dependencies. " @@ -11788,64 +11681,64 @@ msgid "" "`` field." msgstr "" -#: ../source/specifications/core-metadata.rst:524 +#: ../source/specifications/core-metadata.rst:526 msgid "" "A version specifier. Tools parsing the format should accept optional " "parentheses around this, but tools generating it should not use parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:527 +#: ../source/specifications/core-metadata.rst:529 msgid "" "An environment marker after a semicolon. This means that the requirement is " "only needed in the specified conditions." msgstr "" -#: ../source/specifications/core-metadata.rst:530 +#: ../source/specifications/core-metadata.rst:532 msgid "See :pep:`508` for full details of the allowed format." msgstr "" -#: ../source/specifications/core-metadata.rst:532 +#: ../source/specifications/core-metadata.rst:534 msgid "" "The project names should correspond to names as found on the `Python Package " "Index`_." msgstr "" -#: ../source/specifications/core-metadata.rst:535 +#: ../source/specifications/core-metadata.rst:537 msgid "" "Version specifiers must follow the rules described in :doc:`version-" "specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:549 +#: ../source/specifications/core-metadata.rst:551 msgid "Requires-Python" msgstr "" -#: ../source/specifications/core-metadata.rst:553 +#: ../source/specifications/core-metadata.rst:555 msgid "" "This field specifies the Python version(s) that the distribution is " "compatible with. Installation tools may look at this when picking which " "version of a project to install." msgstr "" -#: ../source/specifications/core-metadata.rst:557 +#: ../source/specifications/core-metadata.rst:559 msgid "The value must be in the format specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:559 +#: ../source/specifications/core-metadata.rst:561 msgid "" "For example, if a distribution uses :ref:`f-strings ` " "then it may prevent installation on Python < 3.6 by specifying::" msgstr "" -#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:566 msgid "This field cannot be followed by an environment marker." msgstr "" -#: ../source/specifications/core-metadata.rst:569 +#: ../source/specifications/core-metadata.rst:571 msgid "Requires-External (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:576 +#: ../source/specifications/core-metadata.rst:578 msgid "" "Each entry contains a string describing some dependency in the system that " "the distribution is to be used. This field is intended to serve as a hint " @@ -11853,13 +11746,13 @@ msgid "" "to the ``distutils`` distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:581 +#: ../source/specifications/core-metadata.rst:583 msgid "" "The format of a requirement string is a name of an external dependency, " "optionally followed by a version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:587 +#: ../source/specifications/core-metadata.rst:589 msgid "" "Because they refer to non-Python software releases, version numbers for this " "field are **not** required to conform to the format specified in the :ref:" @@ -11867,36 +11760,36 @@ msgid "" "correspond to the version scheme used by the external dependency." msgstr "" -#: ../source/specifications/core-metadata.rst:592 +#: ../source/specifications/core-metadata.rst:594 msgid "Notice that there is no particular rule on the strings to be used." msgstr "" -#: ../source/specifications/core-metadata.rst:604 +#: ../source/specifications/core-metadata.rst:606 msgid "Project-URL (multiple-use)" msgstr "" -#: ../source/specifications/core-metadata.rst:608 +#: ../source/specifications/core-metadata.rst:610 msgid "" "A string containing a browsable URL for the project and a label for it, " "separated by a comma." msgstr "" -#: ../source/specifications/core-metadata.rst:615 +#: ../source/specifications/core-metadata.rst:617 msgid "The label is free text limited to 32 characters." msgstr "" -#: ../source/specifications/core-metadata.rst:623 +#: ../source/specifications/core-metadata.rst:625 msgid "Provides-Extra (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:626 +#: ../source/specifications/core-metadata.rst:628 msgid "" ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " "required). For older metadata versions, value restrictions were brought into " "line with ``Name:`` and normalization rules were introduced." msgstr "" -#: ../source/specifications/core-metadata.rst:631 +#: ../source/specifications/core-metadata.rst:633 msgid "" "A string containing the name of an optional feature. A valid name consists " "only of lowercase ASCII letters, ASCII numbers, and hyphen. It must start " @@ -11905,13 +11798,13 @@ msgid "" "guarantees unambiguity)::" msgstr "" -#: ../source/specifications/core-metadata.rst:639 +#: ../source/specifications/core-metadata.rst:641 msgid "" "The specified name may be used to make a dependency conditional on whether " "the optional feature has been requested." msgstr "" -#: ../source/specifications/core-metadata.rst:647 +#: ../source/specifications/core-metadata.rst:649 msgid "" "A second distribution requires an optional dependency by placing it inside " "square brackets, and can request multiple features by separating them with a " @@ -11919,20 +11812,20 @@ msgid "" "added to the set of requirements for the distribution." msgstr "" -#: ../source/specifications/core-metadata.rst:657 +#: ../source/specifications/core-metadata.rst:659 msgid "" "Two feature names ``test`` and ``doc`` are reserved to mark dependencies " "that are needed for running automated tests and generating documentation, " "respectively." msgstr "" -#: ../source/specifications/core-metadata.rst:661 +#: ../source/specifications/core-metadata.rst:663 msgid "" "It is legal to specify ``Provides-Extra:`` without referencing it in any " "``Requires-Dist:``." msgstr "" -#: ../source/specifications/core-metadata.rst:664 +#: ../source/specifications/core-metadata.rst:666 msgid "" "When writing data for older metadata versions, names MUST be normalized " "following the same rules used for the ``Name:`` field when performing " @@ -11940,7 +11833,7 @@ msgid "" "Extra:`` entries would clash after being normalized." msgstr "" -#: ../source/specifications/core-metadata.rst:669 +#: ../source/specifications/core-metadata.rst:671 msgid "" "When reading data for older metadata versions, tools SHOULD warn when values " "for this field would be invalid under newer metadata versions. If a value " @@ -11950,11 +11843,11 @@ msgid "" "metadata versions." msgstr "" -#: ../source/specifications/core-metadata.rst:677 +#: ../source/specifications/core-metadata.rst:679 msgid "Rarely Used Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:679 +#: ../source/specifications/core-metadata.rst:681 msgid "" "The fields in this section are currently rarely used, as their design was " "inspired by comparable mechanisms in Linux package management systems, and " @@ -11962,7 +11855,7 @@ msgid "" "open index server such as `PyPI `__." msgstr "" -#: ../source/specifications/core-metadata.rst:684 +#: ../source/specifications/core-metadata.rst:686 msgid "" "As a result, popular installation tools ignore them completely, which in " "turn means there is little incentive for package publishers to set them " @@ -11972,18 +11865,18 @@ msgid "" "package repository." msgstr "" -#: ../source/specifications/core-metadata.rst:694 +#: ../source/specifications/core-metadata.rst:696 msgid "Provides-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:703 msgid "" "Each entry contains a string naming a Distutils project which is contained " "within this distribution. This field *must* include the project identified " "in the ``Name`` field, followed by the version : Name (Version)." msgstr "" -#: ../source/specifications/core-metadata.rst:706 +#: ../source/specifications/core-metadata.rst:708 msgid "" "A distribution may provide additional names, e.g. to indicate that multiple " "projects have been bundled together. For instance, source distributions of " @@ -11992,7 +11885,7 @@ msgid "" "distribution satisfies requirements for both ``ZODB`` and ``transaction``." msgstr "" -#: ../source/specifications/core-metadata.rst:713 +#: ../source/specifications/core-metadata.rst:715 msgid "" "A distribution may also provide a \"virtual\" project name, which does not " "correspond to any separately-distributed project: such a name might be used " @@ -12003,63 +11896,63 @@ msgid "" "them installed." msgstr "" -#: ../source/specifications/core-metadata.rst:721 +#: ../source/specifications/core-metadata.rst:723 msgid "" "A version declaration may be supplied and must follow the rules described " "in :doc:`version-specifiers`. The distribution's version number will be " "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:736 +#: ../source/specifications/core-metadata.rst:738 msgid "Obsoletes-Dist (multiple use)" msgstr "" -#: ../source/specifications/core-metadata.rst:743 +#: ../source/specifications/core-metadata.rst:745 msgid "" "Each entry contains a string describing a distutils project's distribution " "which this distribution renders obsolete, meaning that the two projects " "should not be installed at the same time." msgstr "" -#: ../source/specifications/core-metadata.rst:747 +#: ../source/specifications/core-metadata.rst:749 msgid "" "Version declarations can be supplied. Version numbers must be in the format " "specified in :doc:`version-specifiers`." msgstr "" -#: ../source/specifications/core-metadata.rst:752 +#: ../source/specifications/core-metadata.rst:754 msgid "" "The most common use of this field will be in case a project name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon distribution should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:765 +#: ../source/specifications/core-metadata.rst:767 msgid "Deprecated Fields" msgstr "" -#: ../source/specifications/core-metadata.rst:768 +#: ../source/specifications/core-metadata.rst:770 msgid "Requires" msgstr "" -#: ../source/specifications/core-metadata.rst:771 +#: ../source/specifications/core-metadata.rst:773 msgid "in favour of ``Requires-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:774 +#: ../source/specifications/core-metadata.rst:776 msgid "" "Each entry contains a string describing some other module or package " "required by this package." msgstr "" -#: ../source/specifications/core-metadata.rst:777 +#: ../source/specifications/core-metadata.rst:779 msgid "" "The format of a requirement string is identical to that of a module or " "package name usable with the ``import`` statement, optionally followed by a " "version declaration within parentheses." msgstr "" -#: ../source/specifications/core-metadata.rst:781 +#: ../source/specifications/core-metadata.rst:783 msgid "" "A version declaration is a series of conditional operators and version " "numbers, separated by commas. Conditional operators must be one of \"<\", " @@ -12070,33 +11963,33 @@ msgid "" "version numbers are \"1.0\", \"2.3a2\", \"1.3.99\"," msgstr "" -#: ../source/specifications/core-metadata.rst:789 +#: ../source/specifications/core-metadata.rst:791 msgid "" "Any number of conditional operators can be specified, e.g. the string " "\">1.0, !=1.3.4, <2.0\" is a legal version declaration." msgstr "" -#: ../source/specifications/core-metadata.rst:792 +#: ../source/specifications/core-metadata.rst:794 msgid "" "All of the following are possible requirement strings: \"rfc822\", \"zlib " "(>=1.1.4)\", \"zope\"." msgstr "" -#: ../source/specifications/core-metadata.rst:795 +#: ../source/specifications/core-metadata.rst:797 msgid "" "There’s no canonical list of what strings should be used; the Python " "community is left to choose its own standards." msgstr "" -#: ../source/specifications/core-metadata.rst:808 +#: ../source/specifications/core-metadata.rst:810 msgid "Provides" msgstr "" -#: ../source/specifications/core-metadata.rst:811 +#: ../source/specifications/core-metadata.rst:813 msgid "in favour of ``Provides-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:814 +#: ../source/specifications/core-metadata.rst:816 msgid "" "Each entry contains a string describing a package or module that will be " "provided by this package once it is installed. These strings should match " @@ -12105,3364 +11998,3359 @@ msgid "" "implied if none is specified." msgstr "" -#: ../source/specifications/core-metadata.rst:830 +#: ../source/specifications/core-metadata.rst:832 msgid "Obsoletes" msgstr "" -#: ../source/specifications/core-metadata.rst:833 +#: ../source/specifications/core-metadata.rst:835 msgid "in favour of ``Obsoletes-Dist``" msgstr "" -#: ../source/specifications/core-metadata.rst:836 +#: ../source/specifications/core-metadata.rst:838 msgid "" "Each entry contains a string describing a package or module that this " "package renders obsolete, meaning that the two packages should not be " "installed at the same time. Version declarations can be supplied." msgstr "" -#: ../source/specifications/core-metadata.rst:840 +#: ../source/specifications/core-metadata.rst:842 msgid "" "The most common use of this field will be in case a package name changes, e." "g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " "Torqued Python, the Gorgon package should be removed." msgstr "" -#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:853 msgid "reStructuredText markup: https://docutils.sourceforge.io/" msgstr "" -#: ../source/specifications/core-metadata.rst:856 +#: ../source/specifications/core-metadata.rst:858 msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:6 -msgid "Declaring build system dependencies" +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:8 +#: ../source/specifications/dependency-specifiers.rst:9 msgid "" -"The ``pyproject.toml`` file is written in `TOML `_. Among " -"other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " -"installed in order to run the project's build system successfully." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:15 -msgid "Tables not defined by PyPA specifications are reserved for future use." -msgstr "" - -#: ../source/specifications/declaring-build-dependencies.rst:19 -msgid "build-system table" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:23 +#: ../source/specifications/dependency-specifiers.rst:12 msgid "" -"The ``[build-system]`` table is used to store build-related data. " -"Initially, only one key of the table is valid and is mandatory for the " -"table: ``requires``. This key must have a value of a list of strings " -"representing dependencies required to execute the build system. The strings " -"in this list follow the :ref:`version specifier specification `." +"The job of a dependency is to enable tools like pip [#pip]_ to find the " +"right package to install. Sometimes this is very loose - just specifying a " +"name, and sometimes very specific - referring to a specific file to install. " +"Sometimes dependencies are only relevant in one platform, or only some " +"versions are acceptable, so the language permits describing all these cases." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:30 +#: ../source/specifications/dependency-specifiers.rst:18 msgid "" -"An example ``build-system`` table for a project built with ``setuptools`` is:" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:39 -msgid "" -"Build tools are expected to use the example configuration file above as " -"their default semantics when a ``pyproject.toml`` file is not present." +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/inline-script-metadata.rst:18 +msgid "Specification" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:42 -msgid "" -"Tools should not require the existence of the ``[build-system]`` table. A " -"``pyproject.toml`` file may be used to store configuration details other " -"than build-related data and thus lack a ``[build-system]`` table " -"legitimately. If the file exists but is lacking the ``[build-system]`` table " -"then the default values as specified above should be used. If the table is " -"specified but is missing required fields then the tool should consider it an " -"error." +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:56 -msgid "tool table" +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:58 -msgid "" -"The ``[tool]`` table is where any tool related to your Python project, not " -"just build tools, can have users specify configuration data as long as they " -"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:64 +#: ../source/specifications/dependency-specifiers.rst:42 msgid "" -"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " -"make sure that different projects do not attempt to use the same sub-table " -"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " -"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:71 -msgid "JSON Schema" +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" msgstr "" -#: ../source/specifications/declaring-build-dependencies.rst:73 +#: ../source/specifications/dependency-specifiers.rst:51 msgid "" -"To provide a type-specific representation of the resulting data from the " -"TOML file for illustrative purposes only, the following `JSON Schema " -"`_ would match the data format:" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:5 -msgid "Declaring project metadata" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:7 +#: ../source/specifications/dependency-specifiers.rst:54 msgid "" -":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " -"consume. It defines the following specification as the canonical source for " -"the format used." +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:14 +#: ../source/specifications/dependency-specifiers.rst:59 msgid "" -"This is a **technical, formal specification**. For a gentle, user-friendly " -"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:20 -#: ../source/specifications/dependency-specifiers.rst:24 -#: ../source/specifications/direct-url-data-structure.rst:18 -#: ../source/specifications/direct-url.rst:15 -#: ../source/specifications/inline-script-metadata.rst:18 -msgid "Specification" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:22 +#: ../source/specifications/dependency-specifiers.rst:62 msgid "" -"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " -"specified in the ``pyproject.toml`` file directly and cannot be specified or " -"changed by a tool (this includes data *referred* to by the metadata, e.g. " -"the contents of files referenced by the metadata). Dynamic metadata is " -"listed via the ``dynamic`` key (defined later in this specification) and " -"represents metadata that a tool will later provide." +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined in :rfc:" +"`std-66 <3986>`)::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:30 +#: ../source/specifications/dependency-specifiers.rst:73 msgid "" -"The keys defined in this specification MUST be in a table named " -"``[project]`` in ``pyproject.toml``. No tools may add keys to this table " -"which are not defined by this specification. For tools wishing to store " -"their own settings in ``pyproject.toml``, they may use the ``[tool]`` table " -"as defined in the :ref:`build dependency declaration specification " -"`. The lack of a ``[project]`` table " -"implicitly means the :term:`build backend ` will dynamically " -"provide all keys." -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:39 -msgid "The only keys required to be statically defined are:" +"Environment markers allow making a specification only take effect in some " +"environments::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:43 +#: ../source/specifications/dependency-specifiers.rst:102 msgid "" -"The keys which are required but may be specified *either* statically or " -"listed as dynamic are:" +"Optional components of a distribution may be specified using the extras " +"field::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:48 -msgid "" -"All other keys are considered optional and may be specified statically, " -"listed as dynamic, or left unspecified." +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:51 -msgid "The complete list of keys allowed in the ``[project]`` table are:" +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:53 -msgid "``authors``" +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:55 -msgid "``dependencies``" +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:57 -#: ../source/specifications/declaring-project-metadata.rst:305 -msgid "``dynamic``" +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:58 -msgid "``entry-points``" +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:59 -msgid "``gui-scripts``" +#: ../source/specifications/dependency-specifiers.rst:132 +msgid "Names" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:62 -#, fuzzy -msgid "``maintainers``" -msgstr "維護者" - -#: ../source/specifications/declaring-project-metadata.rst:64 -msgid "``optional-dependencies``" +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:75 -#: ../source/specifications/declaring-project-metadata.rst:87 -#: ../source/specifications/declaring-project-metadata.rst:100 -#: ../source/specifications/declaring-project-metadata.rst:149 -msgid "TOML_ type: string" +#: ../source/specifications/dependency-specifiers.rst:146 +msgid "Extras" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:76 +#: ../source/specifications/dependency-specifiers.rst:148 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Name `" -msgstr "" - -#: ../source/specifications/declaring-project-metadata.rst:79 -msgid "The name of the project." +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:81 +#: ../source/specifications/dependency-specifiers.rst:155 msgid "" -"Tools SHOULD :ref:`normalize ` this name, as soon as it " -"is read for internal consistency." +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:88 +#: ../source/specifications/dependency-specifiers.rst:160 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Version " -"`" +"If multiple extras are listed, all the dependencies are unioned together." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:91 +#: ../source/specifications/dependency-specifiers.rst:163 +#, fuzzy +msgid "Versions" +msgstr "翻譯" + +#: ../source/specifications/dependency-specifiers.rst:165 msgid "" -"The version of the project, as defined in the :ref:`Version specifier " -"specification `." +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:94 -msgid "Users SHOULD prefer to specify already-normalized versions." +#: ../source/specifications/dependency-specifiers.rst:174 +msgid "Environment Markers" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:101 +#: ../source/specifications/dependency-specifiers.rst:176 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Summary " -"`" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:104 -msgid "The summary description of the project." +#: ../source/specifications/dependency-specifiers.rst:183 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:110 -msgid "TOML_ type: string or table" +#: ../source/specifications/dependency-specifiers.rst:186 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described in :" +"pep:`426`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:111 +#: ../source/specifications/dependency-specifiers.rst:191 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Description " -"` and :ref:`Description-Content-Type `" +"Comparisons in marker expressions are typed by the comparison operator. The " +" operators that are not in perform the same as they " +"do for strings in Python. The operators use the version " +"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " +"version specifier). If there is no defined behaviour of this specification " +"and the operator exists in Python, then the operator falls back to the " +"Python behaviour. Otherwise an error should be raised. e.g. the following " +"will result in errors::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:115 -msgid "The full description of the project (i.e. the README)." +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:117 +#: ../source/specifications/dependency-specifiers.rst:211 msgid "" -"The key accepts either a string or a table. If it is a string then it is a " -"path relative to ``pyproject.toml`` to a text file containing the full " -"description. Tools MUST assume the file's encoding is UTF-8. If the file " -"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " -"content-type is ``text/markdown``. If the file path ends in a case-" -"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" -"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " -"the content-type for the user without specifying this key as ``dynamic``. " -"For all unrecognized suffixes when a content-type is not provided, tools " -"MUST raise an error." +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:128 +#: ../source/specifications/dependency-specifiers.rst:216 msgid "" -"The ``readme`` key may also take a table. The ``file`` key has a string " -"value representing a path relative to ``pyproject.toml`` to a file " -"containing the full description. The ``text`` key has a string value which " -"is the full description. These keys are mutually-exclusive, thus tools MUST " -"raise an error if the metadata specifies both keys." +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:135 +#: ../source/specifications/dependency-specifiers.rst:219 msgid "" -"A table specified in the ``readme`` key also has a ``content-type`` key " -"which takes a string specifying the content-type of the full description. A " -"tool MUST raise an error if the metadata does not specify this key in the " -"table. If the metadata does not specify the ``charset`` parameter, then it " -"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " -"Tools MAY support alternative content-types which they can transform to a " -"content-type as supported by the :ref:`core metadata `. " -"Otherwise tools MUST raise an error for unsupported content-types." +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:150 +#: ../source/specifications/dependency-specifiers.rst:223 msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Python `" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:153 -msgid "The Python version requirements of the project." +#: ../source/specifications/dependency-specifiers.rst:233 +msgid "Marker" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:159 -msgid "TOML_ type: table" -msgstr "" +#: ../source/specifications/dependency-specifiers.rst:234 +#, fuzzy +msgid "Python equivalent" +msgstr "Python 版本" -#: ../source/specifications/declaring-project-metadata.rst:160 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`License " -"`" +#: ../source/specifications/dependency-specifiers.rst:235 +msgid "Sample values" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:163 -msgid "" -"The table may have one of two keys. The ``file`` key has a string value that " -"is a file path relative to ``pyproject.toml`` to the file which contains the " -"license for the project. Tools MUST assume the file's encoding is UTF-8. The " -"``text`` key has a string value which is the license of the project. These " -"keys are mutually exclusive, so a tool MUST raise an error if the metadata " -"specifies both keys." +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "``os_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:174 -msgid "TOML_ type: Array of inline tables with string keys and values" +#: ../source/specifications/dependency-specifiers.rst:237 +msgid "``os.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:175 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" -"`Maintainer `, and :ref:`Maintainer-email `" +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``posix``, ``java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:181 -msgid "" -"The people or organizations considered to be the \"authors\" of the project. " -"The exact meaning is open to interpretation — it may list the original or " -"primary authors, current maintainers, or owners of the package." +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``sys_platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:186 -msgid "" -"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " -"is open to interpretation." +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``sys.platform``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:189 +#: ../source/specifications/dependency-specifiers.rst:241 msgid "" -"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " -"Both values must be strings. The ``name`` value MUST be a valid email name " -"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " -"contain commas. The ``email`` value MUST be a valid email address. Both keys " -"are optional, but at least one of the keys must be specified in the table." +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:196 -msgid "" -"Using the data to fill in :ref:`core metadata ` is as follows:" +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``platform_machine``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:199 -msgid "" -"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``platform.machine()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:202 -msgid "" -"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``x86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:206 -msgid "" -"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" -"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``platform_python_implementation``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:210 -msgid "Multiple values should be separated by commas." +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``platform.python_implementation()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:216 -#: ../source/specifications/declaring-project-metadata.rst:226 -msgid "TOML_ type: array of strings" +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "``CPython``, ``Jython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:217 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Keywords " -"`" +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "``platform_release``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:220 -msgid "The keywords for the project." +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "``platform.release()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:227 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Classifier " -"`" +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:230 -msgid "Trove classifiers which apply to the project." +#: ../source/specifications/dependency-specifiers.rst:252 +msgid "``platform_system``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:236 -msgid "TOML_ type: table with keys and values of strings" +#: ../source/specifications/dependency-specifiers.rst:253 +msgid "``platform.system()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:237 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " -"`" +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``Linux``, ``Windows``, ``Java``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:240 -msgid "" -"A table of URLs where the key is the URL label and the value is the URL " -"itself." +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``platform_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:245 -msgid "Entry points" +#: ../source/specifications/dependency-specifiers.rst:256 +msgid "``platform.version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:247 +#: ../source/specifications/dependency-specifiers.rst:257 msgid "" -"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " -"``[project.entry-points]``)" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:249 -msgid ":ref:`Entry points specification `" +#: ../source/specifications/dependency-specifiers.rst:260 +#, fuzzy +msgid "``python_version``" +msgstr "Python 版本" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:251 -msgid "" -"There are three tables related to entry points. The ``[project.scripts]`` " -"table corresponds to the ``console_scripts`` group in the :ref:`entry points " -"specification `. The key of the table is the name of the entry " -"point and the value is the object reference." +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "``3.4``, ``2.7``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:257 -msgid "" -"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " -"in the :ref:`entry points specification `. Its format is the " -"same as ``[project.scripts]``." +#: ../source/specifications/dependency-specifiers.rst:263 +#, fuzzy +msgid "``python_full_version``" +msgstr "Python 版本" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform.python_version()``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:261 -msgid "" -"The ``[project.entry-points]`` table is a collection of tables. Each sub-" -"table's name is an entry point group. The key and value semantics are the " -"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " -"instead keep the entry point groups to only one level deep." +#: ../source/specifications/dependency-specifiers.rst:265 +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.4.0``, ``3.5.0b1``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:267 -msgid "" -"Build back-ends MUST raise an error if the metadata defines a ``[project." -"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " -"table, as they would be ambiguous in the face of ``[project.scripts]`` and " -"``[project.gui-scripts]``, respectively." +#: ../source/specifications/dependency-specifiers.rst:266 +msgid "``implementation_name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:277 -msgid "" -"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " -"values of arrays of :pep:`508` strings (``optional-dependencies``)" +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``sys.implementation.name``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:280 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Requires-" -"Dist ` and :ref:`Provides-Extra `" +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``cpython``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:284 -msgid "The (optional) dependencies of the project." +#: ../source/specifications/dependency-specifiers.rst:269 +msgid "``implementation_version``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:286 -msgid "" -"For ``dependencies``, it is a key whose value is an array of strings. Each " -"string represents a dependency of the project and MUST be formatted as a " -"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " -"` entry." +#: ../source/specifications/dependency-specifiers.rst:270 +msgid "see definition below" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:291 -msgid "" -"For ``optional-dependencies``, it is a table where each key specifies an " -"extra and whose value is an array of strings. The strings of the arrays must " -"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" -"`Provides-Extra `. Each value in the array " -"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``extra``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:307 -msgid "TOML_ type: array of string" +#: ../source/specifications/dependency-specifiers.rst:273 +msgid "" +"An error except when defined by the context interpreting the specification." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:308 -msgid "" -"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " -"`" +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``test``" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:311 +#: ../source/specifications/dependency-specifiers.rst:277 msgid "" -"Specifies which keys listed by this PEP were intentionally unspecified so " -"another tool can/will provide such metadata dynamically. This clearly " -"delineates which metadata is purposefully unspecified and expected to stay " -"unspecified compared to being provided via tooling later on." +"The ``implementation_version`` marker variable is derived from ``sys." +"implementation.version``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:317 +#: ../source/specifications/dependency-specifiers.rst:294 msgid "" -"A build back-end MUST honour statically-specified metadata (which means the " -"metadata did not list the key in ``dynamic``)." +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:319 -msgid "" -"A build back-end MUST raise an error if the metadata specifies ``name`` in " -"``dynamic``." +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "Complete Grammar" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:321 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Required\", then the metadata MUST specify the key statically or list it " -"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " -"should not be possible for a required key to not be listed somehow in the " -"``[project]`` table)." +#: ../source/specifications/dependency-specifiers.rst:300 +msgid "The complete parsley grammar::" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:326 -msgid "" -"If the :ref:`core metadata ` specification lists a field as " -"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " -"a build back-end will provide the data for the key later." +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "A test program - if the grammar is in a string ``grammar``:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:330 +#: ../source/specifications/dependency-specifiers.rst:476 +msgid "Summary of changes to PEP 508" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:478 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key " -"statically as well as being listed in ``dynamic``." +"The following changes were made based on feedback after its initial " +"implementation:" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:332 +#: ../source/specifications/dependency-specifiers.rst:481 msgid "" -"If the metadata does not list a key in ``dynamic``, then a build back-end " -"CANNOT fill in the requisite metadata on behalf of the user (i.e. " -"``dynamic`` is the only way to allow a tool to fill in metadata and the user " -"must opt into the filling in)." +"The definition of ``python_version`` was changed from ``platform." +"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " +"to accommodate potential future versions of Python with 2-digit major and " +"minor versions (e.g. 3.10). [#future_versions]_" msgstr "" -#: ../source/specifications/declaring-project-metadata.rst:336 +#: ../source/specifications/dependency-specifiers.rst:491 msgid "" -"Build back-ends MUST raise an error if the metadata specifies a key in " -"``dynamic`` but the build back-end was unable to determine the data for it " -"(omitting the data, if determined to be the accurate value, is acceptable)." +"pip, the recommended installer for Python packages (http://pip.readthedocs." +"org/en/stable/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:5 -msgid "Dependency specifiers" +#: ../source/specifications/dependency-specifiers.rst:494 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:7 +#: ../source/specifications/dependency-specifiers.rst:497 msgid "" -"This document describes the dependency specifiers format as originally " -"specified in :pep:`508`." +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:10 +#: ../source/specifications/direct-url.rst:8 msgid "" -"The job of a dependency is to enable tools like pip [#pip]_ to find the " -"right package to install. Sometimes this is very loose - just specifying a " -"name, and sometimes very specific - referring to a specific file to install. " -"Sometimes dependencies are only relevant in one platform, or only some " -"versions are acceptable, so the language permits describing all these cases." +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:16 +#: ../source/specifications/direct-url.rst:17 msgid "" -"The language defined is a compact line based format which is already in " -"widespread use in pip requirements files, though we do not specify the " -"command line option handling that those files permit. There is one caveat - " -"the URL reference form, specified in :ref:`Versioning specifier " -"specification ` is not actually implemented in pip, but " -"we use that format rather than pip's current native format." +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:29 -msgid "All features of the language shown with a name based lookup::" +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:232 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:33 -msgid "A minimal URL based lookup::" +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:38 -msgid "Concepts" +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:40 +#: ../source/specifications/direct-url.rst:36 msgid "" -"A dependency specification always specifies a distribution name. It may " -"include extras, which expand the dependencies of the named distribution to " -"enable optional features. The version installed can be controlled using " -"version limits, or giving the URL to a specific artifact to install. Finally " -"the dependency can be made conditional using environment markers." +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when generating :file:" +"`direct_url.json`. For example user:password environment variables should be " +"preserved and ``requested_revision`` should reflect the revision that was " +"provided in the requested URL as faithfully as possible. This information is " +"however *enriched* with more precise data, such as ``commit_id``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:47 -msgid "Grammar" +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:49 -msgid "" -"We first cover the grammar briefly and then drill into the semantics of each " -"section later." +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:52 -msgid "" -"A distribution specification is written in ASCII text. We use a parsley " -"[#parsley]_ grammar to provide a precise grammar. It is expected that the " -"specification will be embedded into a larger system which offers framing " -"such as comments, multiple line support via continuations, or other such " -"features." +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:57 -msgid "" -"The full grammar including annotations to build a useful parse tree is " -"included at the end of this document." +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:60 +#: ../source/specifications/direct-url.rst:51 msgid "" -"Versions may be specified according to the rules of the :ref:`Version " -"specifier specification `. (Note: URI is defined in :rfc:" -"`std-66 <3986>`)::" +"``pip install \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:71 -msgid "" -"Environment markers allow making a specification only take effect in some " -"environments::" +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:100 -msgid "" -"Optional components of a distribution may be specified using the extras " -"field::" +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:109 -msgid "Restrictions on names for extras is defined in :pep:`685`." +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/app." +"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:111 -msgid "Giving us a rule for name based requirements::" +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:115 -msgid "And a rule for direct reference specifications::" +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:119 -msgid "Leading to the unified rule that can specify a dependency.::" +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:124 -msgid "Whitespace" +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:126 +#: ../source/specifications/direct-url.rst:68 msgid "" -"Non line-breaking whitespace is mostly optional with no semantic meaning. " -"The sole exception is detecting the end of a URL requirement." +"March 2020: the ``direct_url.json`` metadata file was originally specified " +"in :pep:`610` and is formally documented here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:130 -msgid "Names" +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:132 +#: ../source/specifications/direct-url-data-structure.rst:9 msgid "" -"Python distribution names are currently defined in :pep:`345`. Names act as " -"the primary identifier for distributions. They are present in all dependency " -"specifications, and are sufficient to be a specification on their own. " -"However, PyPI places strict restrictions on names - they must match a case " -"insensitive regex or they won't be accepted. Accordingly, in this document " -"we limit the acceptable values for identifiers to that regex. A full " -"redefinition of name may take place in a future metadata PEP. The regex (run " -"with re.IGNORECASE) is::" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:144 -msgid "Extras" +#: ../source/specifications/direct-url-data-structure.rst:13 +msgid "" +"The representation of the components of this data structure as a :rfc:`1738` " +"URL is not formally specified at time of writing. A common representation is " +"the pip URL format. Other examples are provided in the :ref:`Version " +"specifier specification `." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:21 msgid "" -"An extra is an optional part of a distribution. Distributions can specify as " -"many extras as they wish, and each extra results in the declaration of " -"additional dependencies of the distribution **when** the extra is used in a " -"dependency specification. For instance::" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:153 +#: ../source/specifications/direct-url-data-structure.rst:24 msgid "" -"Extras union in the dependencies they define with the dependencies of the " -"distribution they are attached to. The example above would result in " -"requests being installed, and requests own dependencies, and also any " -"dependencies that are listed in the \"security\" extra of requests." +"It MUST contain at least two fields. The first one is ``url``, with type " +"``string``. Depending on what ``url`` refers to, the second field MUST be " +"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " +"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " +"local directory). These info fields have a (possibly empty) subdictionary as " +"value, with the possible keys defined below." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:158 +#: ../source/specifications/direct-url-data-structure.rst:31 msgid "" -"If multiple extras are listed, all the dependencies are unioned together." +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:161 -#, fuzzy -msgid "Versions" -msgstr "翻譯" +#: ../source/specifications/direct-url-data-structure.rst:34 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:42 msgid "" -"See the :ref:`Version specifier specification ` for more " -"detail on both version numbers and version comparisons. Version " -"specifications limit the versions of a distribution that can be used. They " -"only apply to distributions looked up by name, rather than via a URL. " -"Version comparison are also used in the markers feature. The optional " -"brackets around a version are present for compatibility with :pep:`345` but " -"should not be generated, only accepted." +"Additionally, the user:password section of the URL MAY be a well-known, non " +"security sensitive string. A typical example is ``git`` in the case of an " +"URL such as ``ssh://git@gitlab.com/user/repo``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:172 -msgid "Environment Markers" +#: ../source/specifications/direct-url-data-structure.rst:47 +msgid "VCS URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:174 +#: ../source/specifications/direct-url-data-structure.rst:49 msgid "" -"Environment markers allow a dependency specification to provide a rule that " -"describes when the dependency should be used. For instance, consider a " -"package that needs argparse. In Python 2.7 argparse is always present. On " -"older Python versions it has to be installed as a dependency. This can be " -"expressed as so::" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:52 msgid "" -"A marker expression evaluates to either True or False. When it evaluates to " -"False, the dependency specification should be ignored." +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:58 msgid "" -"The marker language is inspired by Python itself, chosen for the ability to " -"safely evaluate it without running arbitrary code that could become a " -"security vulnerability. Markers were first standardised in :pep:`345`. This " -"document fixes some issues that were observed in the design described in :" -"pep:`426`." +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:189 +#: ../source/specifications/direct-url-data-structure.rst:60 msgid "" -"Comparisons in marker expressions are typed by the comparison operator. The " -" operators that are not in perform the same as they " -"do for strings in Python. The operators use the version " -"comparison rules of the :ref:`Version specifier specification ` when those are defined (that is when both sides have a valid " -"version specifier). If there is no defined behaviour of this specification " -"and the operator exists in Python, then the operator falls back to the " -"Python behaviour. Otherwise an error should be raised. e.g. the following " -"will result in errors::" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:202 -msgid "" -"User supplied constants are always encoded as strings with either ``'`` or " -"``\"`` quote marks. Note that backslash escapes are not defined, but " -"existing implementations do support them. They are not included in this " -"specification because they add complexity and there is no observable need " -"for them today. Similarly we do not define non-ASCII character support: all " -"the runtime variables we are referencing are expected to be ASCII-only." +#: ../source/specifications/direct-url-data-structure.rst:68 +msgid "Archive URLs" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:209 +#: ../source/specifications/direct-url-data-structure.rst:70 msgid "" -"The variables in the marker grammar such as \"os_name\" resolve to values " -"looked up in the Python runtime. With the exception of \"extra\" all values " -"are defined on all Python versions today - it is an error in the " -"implementation of markers if a value is not defined." +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:214 +#: ../source/specifications/direct-url-data-structure.rst:73 msgid "" -"Unknown variables must raise an error rather than resulting in a comparison " -"that evaluates to True or False." +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:217 +#: ../source/specifications/direct-url-data-structure.rst:76 msgid "" -"Variables whose value cannot be calculated on a given Python implementation " -"should evaluate to ``0`` for versions, and an empty string for all other " -"variables." +"Multiple hashes can be included, and it is up to the consumer to decide what " +"to do with multiple hashes (it may validate all of them or a subset of them, " +"or nothing at all)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:221 -msgid "" -"The \"extra\" variable is special. It is used by wheels to signal which " -"specifications apply to a given extra in the wheel ``METADATA`` file, but " -"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " -"is no current specification for this. Regardless, outside of a context where " -"this special handling is taking place, the \"extra\" variable should result " -"in an error like all other unknown variables." +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "These hash names SHOULD always be normalized to be lowercase." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:231 -msgid "Marker" +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"Any hash algorithm available via ``hashlib`` (specifically any that can be " +"passed to ``hashlib.new()`` and do not require additional parameters) can be " +"used as a key for the hashes dictionary. At least one secure algorithm from " +"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " +"writing, ``sha256`` specifically is recommended." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:232 -#, fuzzy -msgid "Python equivalent" -msgstr "Python 版本" - -#: ../source/specifications/dependency-specifiers.rst:233 -msgid "Sample values" +#: ../source/specifications/direct-url-data-structure.rst:88 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:234 -msgid "``os_name``" +#: ../source/specifications/direct-url-data-structure.rst:91 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:235 -msgid "``os.name``" +#: ../source/specifications/direct-url-data-structure.rst:95 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:236 -msgid "``posix``, ``java``" +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "Local directories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:237 -msgid "``sys_platform``" +#: ../source/specifications/direct-url-data-structure.rst:102 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:238 -msgid "``sys.platform``" +#: ../source/specifications/direct-url-data-structure.rst:105 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:239 +#: ../source/specifications/direct-url-data-structure.rst:108 msgid "" -"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " -"from Python3 and \"linux2\" from Python2)" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:241 -msgid "``platform_machine``" +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Projects in subdirectories" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:242 -msgid "``platform.machine()``" +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:243 -msgid "``x86_64``" +#: ../source/specifications/direct-url-data-structure.rst:121 +msgid "Registered VCS" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:244 -msgid "``platform_python_implementation``" +#: ../source/specifications/direct-url-data-structure.rst:123 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:245 -msgid "``platform.python_implementation()``" +#: ../source/specifications/direct-url-data-structure.rst:133 +msgid "Git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:246 -msgid "``CPython``, ``Jython``" +#: ../source/specifications/direct-url-data-structure.rst:136 +#: ../source/specifications/direct-url-data-structure.rst:163 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "Home page" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:247 -msgid "``platform_release``" +#: ../source/specifications/direct-url-data-structure.rst:136 +msgid "https://git-scm.com/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:248 -msgid "``platform.release()``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +msgid "vcs command" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:249 -msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +#: ../source/specifications/direct-url-data-structure.rst:139 +#: ../source/specifications/direct-url-data-structure.rst:142 +msgid "git" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:250 -msgid "``platform_system``" +#: ../source/specifications/direct-url-data-structure.rst:142 +#: ../source/specifications/direct-url-data-structure.rst:169 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "``vcs`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:251 -msgid "``platform.system()``" +#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/direct-url-data-structure.rst:172 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:209 +msgid "``requested_revision`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:252 -msgid "``Linux``, ``Windows``, ``Java``" +#: ../source/specifications/direct-url-data-structure.rst:145 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:253 -msgid "``platform_version``" +#: ../source/specifications/direct-url-data-structure.rst:149 +#: ../source/specifications/direct-url-data-structure.rst:175 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "``commit_id`` field" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:254 -msgid "``platform.version()``" +#: ../source/specifications/direct-url-data-structure.rst:149 +msgid "A commit hash (40 hexadecimal characters sha1)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:255 +#: ../source/specifications/direct-url-data-structure.rst:153 msgid "" -"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " -"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " -"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:258 -#, fuzzy -msgid "``python_version``" -msgstr "Python 版本" - -#: ../source/specifications/dependency-specifiers.rst:259 -msgid "``'.'.join(platform.python_version_tuple()[:2])``" +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "Mercurial" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:260 -msgid "``3.4``, ``2.7``" +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "https://www.mercurial-scm.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:261 -#, fuzzy -msgid "``python_full_version``" -msgstr "Python 版本" +#: ../source/specifications/direct-url-data-structure.rst:166 +#: ../source/specifications/direct-url-data-structure.rst:169 +msgid "hg" +msgstr "" -#: ../source/specifications/dependency-specifiers.rst:262 -msgid "``platform.python_version()``" +#: ../source/specifications/direct-url-data-structure.rst:172 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:263 -#: ../source/specifications/dependency-specifiers.rst:269 -msgid "``3.4.0``, ``3.5.0b1``" +#: ../source/specifications/direct-url-data-structure.rst:175 +msgid "A changeset ID (40 hexadecimal characters)." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:264 -msgid "``implementation_name``" +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Bazaar" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:265 -msgid "``sys.implementation.name``" +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.breezy-vcs.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:266 -msgid "``cpython``" +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "bzr" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:267 -msgid "``implementation_version``" +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:268 -msgid "see definition below" +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A revision id." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:270 -msgid "``extra``" +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Subversion" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:271 -msgid "" -"An error except when defined by the context interpreting the specification." +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://subversion.apache.org/" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:273 -msgid "``test``" +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "svn" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:275 +#: ../source/specifications/direct-url-data-structure.rst:208 msgid "" -"The ``implementation_version`` marker variable is derived from ``sys." -"implementation.version``::" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:290 +#: ../source/specifications/direct-url-data-structure.rst:212 msgid "" -"This environment markers section, initially defined through :pep:`508`, " -"supersedes the environment markers section in :pep:`345`." +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:294 -msgid "Complete Grammar" +#: ../source/specifications/direct-url-data-structure.rst:219 +msgid "Source archive:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:296 -msgid "The complete parsley grammar::" +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "Git URL with tag and commit-hash:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:403 -msgid "A test program - if the grammar is in a string ``grammar``::" +#: ../source/specifications/direct-url-data-structure.rst:245 +msgid "Local directory:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:470 -msgid "Summary of changes to PEP 508" +#: ../source/specifications/direct-url-data-structure.rst:254 +msgid "Local directory in editable mode:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:472 +#: ../source/specifications/direct-url-data-structure.rst:268 msgid "" -"The following changes were made based on feedback after its initial " -"implementation:" +"March 2020: this data structure was originally specified as part of the " +"``direct_url.json`` metadata file in :pep:`610` and is formally documented " +"here." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:475 +#: ../source/specifications/direct-url-data-structure.rst:270 msgid "" -"The definition of ``python_version`` was changed from ``platform." -"python_version()[:3]`` to ``'.'.join(platform.python_version_tuple()[:2])``, " -"to accommodate potential future versions of Python with 2-digit major and " -"minor versions (e.g. 3.10). [#future_versions]_" +"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +"discuss.python.org/t/22299))." msgstr "" -#: ../source/specifications/dependency-specifiers.rst:485 -msgid "" -"pip, the recommended installer for Python packages (http://pip.readthedocs." -"org/en/stable/)" +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:488 -msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" msgstr "" -#: ../source/specifications/dependency-specifiers.rst:491 +#: ../source/specifications/entry-points.rst:11 msgid "" -"Future Python versions might be problematic with the definition of " -"Environment Marker Variable ``python_version`` (https://github.com/python/" -"peps/issues/560)" +"Distributions can specify ``console_scripts`` entry points, each referring " +"to a function. When *pip* (or another console_scripts aware installer) " +"installs the distribution, it will create a command-line wrapper for each " +"entry point." msgstr "" -#: ../source/specifications/direct-url.rst:6 -msgid "Recording the Direct URL Origin of installed distributions" +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." msgstr "" -#: ../source/specifications/direct-url.rst:8 +#: ../source/specifications/entry-points.rst:19 msgid "" -"This document specifies a :file:`direct_url.json` file in the ``*.dist-" -"info`` directory of an installed distribution, to record the Direct URL " -"Origin of the distribution. The general structure and usage of ``*.dist-" -"info`` directories is described in :ref:`recording-installed-packages`." +"The entry point file format was originally developed to allow packages built " +"with setuptools to provide integration point metadata that would be read at " +"runtime with ``importlib.metadata``. It is now defined as a PyPA " +"interoperability specification in order to allow build tools other than " +"setuptools to publish ``importlib.metadata`` compatible entry point " +"metadata, and runtime libraries other than ``importlib.metadata`` to " +"portably read published entry point metadata (potentially with different " +"caching and conflict resolution strategies)." msgstr "" -#: ../source/specifications/direct-url.rst:17 -msgid "" -"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " -"directory by installers when installing a distribution from a requirement " -"specifying a direct URL reference (including a VCS URL)." +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" msgstr "" -#: ../source/specifications/direct-url.rst:21 -#: ../source/specifications/recording-installed-packages.rst:230 -msgid "" -"This file MUST NOT be created when installing a distribution from an other " -"type of requirement (i.e. name plus version specifier)." +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" msgstr "" -#: ../source/specifications/direct-url.rst:24 +#: ../source/specifications/entry-points.rst:32 msgid "" -"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " -"of the :doc:`direct-url-data-structure`." +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while ``pygments." +"styles`` is the group for classes defining pygments styles. The consumer " +"typically defines the expected interface. To avoid clashes, consumers " +"defining a new group should use names starting with a PyPI name owned by the " +"consumer project, followed by ``.``. Group names must be one or more groups " +"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." +"\\w+)*$``)." msgstr "" -#: ../source/specifications/direct-url.rst:29 +#: ../source/specifications/entry-points.rst:42 msgid "" -"When the requested URL has the file:// scheme and points to a local " -"directory that happens to contain a VCS checkout, installers MUST NOT " -"attempt to infer any VCS information and therefore MUST NOT output any VCS " -"related information (such as ``vcs_info``) in :file:`direct_url.json`." +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." msgstr "" -#: ../source/specifications/direct-url.rst:36 +#: ../source/specifications/entry-points.rst:51 msgid "" -"As a general rule, installers should as much as possible preserve the " -"information that was provided in the requested URL when generating :file:" -"`direct_url.json`. For example user:password environment variables should be " -"preserved and ``requested_revision`` should reflect the revision that was " -"provided in the requested URL as faithfully as possible. This information is " -"however *enriched* with more precise data, such as ``commit_id``." +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" msgstr "" -#: ../source/specifications/direct-url.rst:45 -msgid "Example pip commands and their effect on direct_url.json" +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." msgstr "" -#: ../source/specifications/direct-url.rst:47 -msgid "Commands that generate a ``direct_url.json``:" +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." msgstr "" -#: ../source/specifications/direct-url.rst:49 -msgid "``pip install https://example.com/app-1.0.tgz``" +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." msgstr "" -#: ../source/specifications/direct-url.rst:50 -msgid "``pip install https://example.com/app-1.0.whl``" +#: ../source/specifications/entry-points.rst:80 +msgid "File format" msgstr "" -#: ../source/specifications/direct-url.rst:51 +#: ../source/specifications/entry-points.rst:82 msgid "" -"``pip install \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"``" +"Entry points are defined in a file called :file:`entry_points.txt` in the :" +"file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." msgstr "" -#: ../source/specifications/direct-url.rst:52 -msgid "``pip install ./app``" +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" msgstr "" -#: ../source/specifications/direct-url.rst:53 -msgid "``pip install file:///home/user/app``" +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." msgstr "" -#: ../source/specifications/direct-url.rst:54 +#: ../source/specifications/entry-points.rst:101 msgid "" -"``pip install --editable \"app @ git+https://example.com/repo/app." -"git#subdirectory=setup\"`` (in which case, ``url`` will be the local " -"directory where the git repository has been cloned to, and ``dir_info`` will " -"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." msgstr "" -#: ../source/specifications/direct-url.rst:58 -msgid "``pip install -e ./app``" +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." msgstr "" -#: ../source/specifications/direct-url.rst:60 -msgid "Commands that *do not* generate a ``direct_url.json``" +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" msgstr "" -#: ../source/specifications/direct-url.rst:62 -msgid "``pip install app``" +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." msgstr "" -#: ../source/specifications/direct-url.rst:63 -msgid "``pip install app --no-index --find-links https://example.com/``" +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:283 -#: ../source/specifications/direct-url.rst:66 -#: ../source/specifications/externally-managed-environments.rst:472 -#: ../source/specifications/inline-script-metadata.rst:239 -#: ../source/specifications/name-normalization.rst:42 -#: ../source/specifications/source-distribution-format.rst:144 -#: ../source/specifications/version-specifiers.rst:1256 -msgid "History" +#: ../source/specifications/entry-points.rst:145 +msgid "" +"The difference between ``console_scripts`` and ``gui_scripts`` only affects " +"Windows systems. ``console_scripts`` are wrapped in a console executable, so " +"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " +"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " +"executable, so they can be started without a console, but cannot use " +"standard streams unless application code redirects them. Other platforms do " +"not have the same distinction." msgstr "" -#: ../source/specifications/direct-url.rst:68 +#: ../source/specifications/entry-points.rst:153 msgid "" -"March 2020: the ``direct_url.json`` metadata file was originally specified " -"in :pep:`610` and is formally documented here." +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:6 -msgid "Direct URL Data Structure" +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:8 -msgid "" -"This document specifies a JSON-serializable abstract data structure that can " -"represent URLs to python projects and distribution artifacts such as VCS " -"source trees, local source trees, source distributions and wheels." +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:12 +#: ../source/specifications/externally-managed-environments.rst:8 msgid "" -"The representation of the components of this data structure as a :rfc:`1738` " -"URL is not formally specified at time of writing. A common representation is " -"the pip URL format. Other examples are provided in the :ref:`Version " -"specifier specification `." +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:20 +#: ../source/specifications/externally-managed-environments.rst:13 msgid "" -"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " -"according to :rfc:`8259`." +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:23 +#: ../source/specifications/externally-managed-environments.rst:18 msgid "" -"It MUST contain at least two fields. The first one is ``url``, with type " -"``string``. Depending on what ``url`` refers to, the second field MUST be " -"one of ``vcs_info`` (if ``url`` is a VCS reference), ``archive_info`` (if " -"``url`` is a source archives or a wheel), or ``dir_info`` (if ``url`` is a " -"local directory). These info fields have a (possibly empty) subdictionary as " -"value, with the possible keys defined below." +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:30 +#: ../source/specifications/externally-managed-environments.rst:24 msgid "" -"When persisted, ``url`` MUST be stripped of any sensitive authentication " -"information, for security reasons." +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:33 -msgid "" -"The user:password section of the URL MAY however be composed of environment " -"variables, matching the following regular expression::" +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:39 +#: ../source/specifications/externally-managed-environments.rst:34 msgid "" -"Additionally, the user:password section of the URL MAY be a well-known, non " -"security sensitive string. A typical example is ``git`` in the case of an " -"URL such as ``ssh://git@gitlab.com/user/repo``." +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:44 -msgid "VCS URLs" +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:46 +#: ../source/specifications/externally-managed-environments.rst:39 msgid "" -"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " -"present as a dictionary with the following keys:" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:49 +#: ../source/specifications/externally-managed-environments.rst:46 msgid "" -"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " -"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " -"registered by writing a PEP to amend this specification. The ``url`` value " -"MUST be compatible with the corresponding VCS, so an installer can hand it " -"off without transformation to a checkout/download command of the VCS." +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:55 +#: ../source/specifications/externally-managed-environments.rst:51 msgid "" -"A ``requested_revision`` key (type ``string``) MAY be present naming a " -"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS)." +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:57 +#: ../source/specifications/externally-managed-environments.rst:60 msgid "" -"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " -"commit/revision number that was/is to be installed. If the VCS supports " -"commit-hash based revision identifiers, such commit-hash MUST be used as " -"``commit_id`` in order to reference an immutable version of the source code." +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:65 -msgid "Archive URLs" -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "Package Index" +msgid "package" +msgstr "套件索引" -#: ../source/specifications/direct-url-data-structure.rst:67 +#: ../source/specifications/externally-managed-environments.rst:64 msgid "" -"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " -"MUST be present as a dictionary with the following keys:" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call a :term:" +"`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:70 +#: ../source/specifications/externally-managed-environments.rst:70 msgid "" -"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " -"hex encoded digest of the file." +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:73 +#: ../source/specifications/externally-managed-environments.rst:75 msgid "" -"Multiple hashes can be included, and it is up to the consumer to decide what " -"to do with multiple hashes (it may validate all of them or a subset of them, " -"or nothing at all)." +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package." +"\" (Again, in many cases, a Python package is shipped inside a distro's " +"package named something like ``python-`` plus the Python package name.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:77 -msgid "These hash names SHOULD always be normalized to be lowercase." -msgstr "" +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "安裝軟體套件" -#: ../source/specifications/direct-url-data-structure.rst:79 +#: ../source/specifications/externally-managed-environments.rst:82 msgid "" -"Any hash algorithm available via ``hashlib`` (specifically any that can be " -"passed to ``hashlib.new()`` and do not require additional parameters) can be " -"used as a key for the hashes dictionary. At least one secure algorithm from " -"``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of " -"writing, ``sha256`` specifically is recommended." +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:85 +#: ../source/specifications/externally-managed-environments.rst:92 msgid "" -"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " -"compatibility purposes, with value ``=``." +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:88 +#: ../source/specifications/externally-managed-environments.rst:96 msgid "" -"Producers of the data structure SHOULD emit the ``hashes`` key whether one " -"or multiple hashes are available. Producers SHOULD continue to emit the " -"``hash`` key in contexts where they did so before, so as to keep backwards " -"compatibility for existing clients." +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:92 -msgid "" -"When both the ``hash`` and ``hashes`` keys are present, the hash represented " -"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " -"consumers can consider the ``hashes`` key only if it is present, and fall " -"back to ``hash`` otherwise." +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:97 -msgid "Local directories" +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:99 +#: ../source/specifications/externally-managed-environments.rst:117 msgid "" -"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " -"present as a dictionary with the following key:" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:102 -msgid "" -"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " -"installed in editable mode, ``false`` otherwise. If absent, default to " -"``false``." +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:105 +#: ../source/specifications/externally-managed-environments.rst:121 msgid "" -"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " -"and be compliant with :rfc:`8089`. In particular, the path component must be " -"absolute. Symbolic links SHOULD be preserved when making relative paths " -"absolute." +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:111 -msgid "Projects in subdirectories" +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:113 +#: ../source/specifications/externally-managed-environments.rst:134 msgid "" -"A top-level ``subdirectory`` field MAY be present containing a directory " -"path, relative to the root of the VCS repository, source archive or local " -"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:118 -msgid "Registered VCS" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:120 +#: ../source/specifications/externally-managed-environments.rst:142 msgid "" -"This section lists the registered VCS's; expanded, VCS-specific information " -"on how to use the ``vcs``, ``requested_revision``, and other fields of " -"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " -"support other VCS's although it is RECOMMENDED to register them by writing a " -"PEP to amend this specification. The ``vcs`` field SHOULD be the command " -"name (lowercased). Additional fields that would be necessary to support such " -"VCS SHOULD be prefixed with the VCS command name." +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:130 -msgid "Git" +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:132 -#: ../source/specifications/direct-url-data-structure.rst:164 -#: ../source/specifications/direct-url-data-structure.rst:187 -#: ../source/specifications/direct-url-data-structure.rst:210 -msgid "Home page" +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:134 -msgid "https://git-scm.com/" +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:136 -#: ../source/specifications/direct-url-data-structure.rst:168 -#: ../source/specifications/direct-url-data-structure.rst:191 -#: ../source/specifications/direct-url-data-structure.rst:214 -msgid "vcs command" +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:138 -#: ../source/specifications/direct-url-data-structure.rst:142 -msgid "git" +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:140 -#: ../source/specifications/direct-url-data-structure.rst:172 -#: ../source/specifications/direct-url-data-structure.rst:195 -#: ../source/specifications/direct-url-data-structure.rst:218 -msgid "``vcs`` field" +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:144 -#: ../source/specifications/direct-url-data-structure.rst:176 -#: ../source/specifications/direct-url-data-structure.rst:199 -#: ../source/specifications/direct-url-data-structure.rst:222 -msgid "``requested_revision`` field" +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:146 +#: ../source/specifications/externally-managed-environments.rst:182 msgid "" -"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " -"other commit-ish." -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:149 -#: ../source/specifications/direct-url-data-structure.rst:180 -#: ../source/specifications/direct-url-data-structure.rst:203 -#: ../source/specifications/direct-url-data-structure.rst:227 -msgid "``commit_id`` field" -msgstr "" - -#: ../source/specifications/direct-url-data-structure.rst:151 -msgid "A commit hash (40 hexadecimal characters sha1)." +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:155 +#: ../source/specifications/externally-managed-environments.rst:200 msgid "" -"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " -"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " -"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " -"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:162 -msgid "Mercurial" +#: ../source/specifications/externally-managed-environments.rst:206 +msgid "" +"Software distributors who have a non-Python-specific package manager that " +"manages libraries in the ``sys.path`` of their Python package should, in " +"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " +"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" +"EXTERNALLY-MANAGED`` consisting of something like" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:166 -msgid "https://www.mercurial-scm.org/" +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:170 -#: ../source/specifications/direct-url-data-structure.rst:174 -msgid "hg" +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:178 -msgid "A tag name, branch name, changeset ID, shortened changeset ID." +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:182 -msgid "A changeset ID (40 hexadecimal characters)." +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:185 -msgid "Bazaar" +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:189 -msgid "https://www.breezy-vcs.org/" +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:193 -#: ../source/specifications/direct-url-data-structure.rst:197 -msgid "bzr" +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:201 -msgid "A tag name, branch name, revision id." +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:205 -msgid "A revision id." +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:208 -msgid "Subversion" +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:212 -msgid "https://subversion.apache.org/" +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:216 -#: ../source/specifications/direct-url-data-structure.rst:220 -msgid "svn" +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:224 +#: ../source/specifications/externally-managed-environments.rst:285 msgid "" -"``requested_revision`` must be compatible with ``svn checkout`` ``--" -"revision`` option. In Subversion, branch or tag is part of ``url``." +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:229 +#: ../source/specifications/externally-managed-environments.rst:293 msgid "" -"Since Subversion does not support globally unique identifiers, this field is " -"the Subversion revision number in the corresponding repository." +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:236 -msgid "Source archive:" +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:249 -msgid "Git URL with tag and commit-hash:" +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers (e." +"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:262 -msgid "Local directory:" +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:271 -msgid "Local directory in editable mode:" +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's ``sys." +"path``, one for distro-installed packages and one for packages installed by " +"the local system administrator, and configure ``sysconfig." +"get_default_scheme()`` to point at the latter path. This ensures that tools " +"like pip will not modify distro-installed packages. The path for the local " +"system administrator should come before the distro path on ``sys.path`` so " +"that local installs take preference over distro packages." msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:285 +#: ../source/specifications/externally-managed-environments.rst:328 msgid "" -"March 2020: this data structure was originally specified as part of the " -"``direct_url.json`` metadata file in :pep:`610` and is formally documented " -"here." +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" msgstr "" -#: ../source/specifications/direct-url-data-structure.rst:287 +#: ../source/specifications/externally-managed-environments.rst:341 msgid "" -"January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" -"discuss.python.org/t/22299))." +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." msgstr "" -#: ../source/specifications/entry-points.rst:5 -msgid "Entry points specification" +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." msgstr "" -#: ../source/specifications/entry-points.rst:7 +#: ../source/specifications/externally-managed-environments.rst:355 msgid "" -"*Entry points* are a mechanism for an installed distribution to advertise " -"components it provides to be discovered and used by other code. For example:" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." msgstr "" -#: ../source/specifications/entry-points.rst:11 +#: ../source/specifications/externally-managed-environments.rst:367 msgid "" -"Distributions can specify ``console_scripts`` entry points, each referring " -"to a function. When *pip* (or another console_scripts aware installer) " -"installs the distribution, it will create a command-line wrapper for each " -"entry point." +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." msgstr "" -#: ../source/specifications/entry-points.rst:14 +#: ../source/specifications/externally-managed-environments.rst:377 msgid "" -"Applications can use entry points to load plugins; e.g. Pygments (a syntax " -"highlighting tool) can use additional lexers and styles from separately " -"installed packages. For more about this, see :doc:`/guides/creating-and-" -"discovering-plugins`." +"To install packages with pip, you would also need to either suppress the " +"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " +"the command line. You may want to use the same means for suppressing the " +"marker file in build chroots as you do in container images." msgstr "" -#: ../source/specifications/entry-points.rst:19 +#: ../source/specifications/externally-managed-environments.rst:383 msgid "" -"The entry point file format was originally developed to allow packages built " -"with setuptools to provide integration point metadata that would be read at " -"runtime with ``importlib.metadata``. It is now defined as a PyPA " -"interoperability specification in order to allow build tools other than " -"setuptools to publish ``importlib.metadata`` compatible entry point " -"metadata, and runtime libraries other than ``importlib.metadata`` to " -"portably read published entry point metadata (potentially with different " -"caching and conflict resolution strategies)." +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." msgstr "" -#: ../source/specifications/entry-points.rst:28 -msgid "Data model" +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." msgstr "" -#: ../source/specifications/entry-points.rst:30 -msgid "Conceptually, an entry point is defined by three required properties:" +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." msgstr "" -#: ../source/specifications/entry-points.rst:32 +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "文件類型" + +#: ../source/specifications/externally-managed-environments.rst:412 msgid "" -"The **group** that an entry point belongs to indicates what sort of object " -"it provides. For instance, the group ``console_scripts`` is for entry points " -"referring to functions which can be used as a command, while ``pygments." -"styles`` is the group for classes defining pygments styles. The consumer " -"typically defines the expected interface. To avoid clashes, consumers " -"defining a new group should use names starting with a PyPI name owned by the " -"consumer project, followed by ``.``. Group names must be one or more groups " -"of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\." -"\\w+)*$``)." +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." msgstr "" -#: ../source/specifications/entry-points.rst:42 +#: ../source/specifications/externally-managed-environments.rst:415 msgid "" -"The **name** identifies this entry point within its group. The precise " -"meaning of this is up to the consumer. For console scripts, the name of the " -"entry point is the command that will be used to launch it. Within a " -"distribution, entry point names should be unique. If different distributions " -"provide the same name, the consumer decides how to handle such conflicts. " -"The name may contain any characters except ``=``, but it cannot start or end " -"with any whitespace character, or start with ``[``. For new entry points, it " -"is recommended to use only letters, numbers, underscores, dots and dashes " -"(regex ``[\\w.-]+``)." +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" msgstr "" -#: ../source/specifications/entry-points.rst:51 -msgid "" -"The **object reference** points to a Python object. It is either in the form " -"``importable.module``, or ``importable.module:object.attr``. Each of the " -"parts delimited by dots and the colon is a valid Python identifier. It is " -"intended to be looked up like this::" +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" msgstr "" -#: ../source/specifications/entry-points.rst:64 +#: ../source/specifications/externally-managed-environments.rst:420 msgid "" -"Some tools call this kind of object reference by itself an 'entry point', " -"for want of a better term, especially where it points to a function to " -"launch a program." +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:68 -msgid "" -"There is also an optional property: the **extras** are a set of strings " -"identifying optional features of the distribution providing the entry point. " -"If these are specified, the entry point requires the dependencies of those " -"'extras'. See the metadata field :ref:`metadata_provides_extra`." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" msgstr "" -#: ../source/specifications/entry-points.rst:73 -msgid "" -"Using extras for an entry point is no longer recommended. Consumers should " -"support parsing them from existing distributions, but may then ignore them. " -"New publishing tools need not support specifying extras. The functionality " -"of handling extras was tied to setuptools' model of managing 'egg' packages, " -"but newer tools such as pip and virtualenv use a different model." +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." msgstr "" -#: ../source/specifications/entry-points.rst:80 -msgid "File format" +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" msgstr "" -#: ../source/specifications/entry-points.rst:82 +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 msgid "" -"Entry points are defined in a file called :file:`entry_points.txt` in the :" -"file:`*.dist-info` directory of the distribution. This is the directory " -"described in :ref:`recording-installed-packages` for installed " -"distributions, and in :ref:`binary-distribution-format` for wheels. The file " -"uses the UTF-8 character encoding." +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." msgstr "" -#: ../source/specifications/entry-points.rst:88 +#: ../source/specifications/externally-managed-environments.rst:433 msgid "" -"The file contents are in INI format, as read by Python's :mod:`configparser` " -"module. However, configparser treats names as case-insensitive by default, " -"whereas entry point names are case sensitive. A case-sensitive config parser " -"can be made like this::" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." +"get_path(\"stdlib\")``." msgstr "" -#: ../source/specifications/entry-points.rst:98 +#: ../source/specifications/externally-managed-environments.rst:445 msgid "" -"The entry points file must always use ``=`` to delimit names from values " -"(whereas configparser also allows using ``:``)." +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." msgstr "" -#: ../source/specifications/entry-points.rst:101 +#: ../source/specifications/externally-managed-environments.rst:454 msgid "" -"The sections of the config file represent entry point groups, the names are " -"names, and the values encode both the object reference and the optional " -"extras. If extras are used, they are a comma-separated list inside square " -"brackets." +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." msgstr "" -#: ../source/specifications/entry-points.rst:105 +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 msgid "" -"Within a value, readers must accept and ignore spaces (including multiple " -"consecutive spaces) before or after the colon, between the object reference " -"and the left square bracket, between the extra names and the square brackets " -"and colons delimiting them, and after the right square bracket. The syntax " -"for extras is formally specified as part of :pep:`508` (as ``extras``) and " -"restrictions on values specified in :pep:`685`. For tools writing the file, " -"it is recommended only to insert a space between the object reference and " -"the left square bracket." +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." msgstr "" -#: ../source/specifications/entry-points.rst:114 -#: ../source/specifications/version-specifiers.rst:199 -msgid "For example::" +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "This specification was originally approved as :pep:`668`." msgstr "" -#: ../source/specifications/entry-points.rst:126 -msgid "Use for scripts" +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" msgstr "" -#: ../source/specifications/entry-points.rst:128 +#: ../source/specifications/index.rst:6 msgid "" -"Two groups of entry points have special significance in packaging: " -"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " -"entry point should be usable as a command in a system shell after the " -"package is installed. The object reference points to a function which will " -"be called with no arguments when this command is run. The function may " -"return an integer to be used as a process exit code, and returning ``None`` " -"is equivalent to returning ``0``." +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." msgstr "" -#: ../source/specifications/entry-points.rst:136 -msgid "" -"For instance, the entry point ``mycmd = mymod:main`` would create a command " -"``mycmd`` launching a script like this::" +#: ../source/specifications/inline-script-metadata.rst:3 +msgid "Inline script metadata" msgstr "" -#: ../source/specifications/entry-points.rst:143 +#: ../source/specifications/inline-script-metadata.rst:6 msgid "" -"The difference between ``console_scripts`` and ``gui_scripts`` only affects " -"Windows systems. ``console_scripts`` are wrapped in a console executable, so " -"they are attached to a console and can use ``sys.stdin``, ``sys.stdout`` and " -"``sys.stderr`` for input and output. ``gui_scripts`` are wrapped in a GUI " -"executable, so they can be started without a console, but cannot use " -"standard streams unless application code redirects them. Other platforms do " -"not have the same distinction." +"This specification has been **provisionally accepted**. It is subject to " +"being changed or abandoned. See the `PEP 723 conditional acceptance thread " +"`_ for details." msgstr "" -#: ../source/specifications/entry-points.rst:151 +#: ../source/specifications/inline-script-metadata.rst:12 msgid "" -"Install tools are expected to set up wrappers for both ``console_scripts`` " -"and ``gui_scripts`` in the scripts directory of the install scheme. They are " -"not responsible for putting this directory in the ``PATH`` environment " -"variable which defines where command-line tools are found." +"This specification defines a metadata format that can be embedded in single-" +"file Python scripts to assist launchers, IDEs and other external tools which " +"may need to interact with such scripts." msgstr "" -#: ../source/specifications/entry-points.rst:156 +#: ../source/specifications/inline-script-metadata.rst:20 msgid "" -"As files are created from the names, and some filesystems are case-" -"insensitive, packages should avoid using names in these groups which differ " -"only in case. The behaviour of install tools when names differ only in case " -"is undefined." +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:6 -msgid "Externally Managed Environments" +#: ../source/specifications/inline-script-metadata.rst:25 +msgid "" +"Any Python script may have top-level comment blocks that MUST start with the " +"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " +"That is: a single ``#``, followed by a single space, followed by three " +"forward slashes, followed by a single space, followed by the type of " +"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " +"followed by a single space, followed by three forward slashes. The ``TYPE`` " +"MUST only consist of ASCII letters, numbers and hyphens." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:8 +#: ../source/specifications/inline-script-metadata.rst:33 msgid "" -"While some Python installations are entirely managed by the user that " -"installed Python, others may be provided and managed by another means (such " -"as the operating system package manager in a Linux distribution, or as a " -"bundled Python environment in an application with a dedicated installer)." +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:13 +#: ../source/specifications/inline-script-metadata.rst:40 msgid "" -"Attempting to use conventional Python packaging tools to manipulate such " -"environments can be confusing at best and outright break the entire " -"underlying operating system at worst. Documentation and interoperability " -"guides only go so far in resolving such problems." +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:18 +#: ../source/specifications/inline-script-metadata.rst:56 msgid "" -"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " -"a Python installation to indicate to Python-specific tools such as ``pip`` " -"that they neither install nor remove packages into the interpreter’s default " -"installation environment, and should instead guide the end user towards " -"using :ref:`virtual-environments`." +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:24 +#: ../source/specifications/inline-script-metadata.rst:59 msgid "" -"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " -"if a Python-specific package manager is about to install a package in an " -"interpreter-wide context, it can do so in a manner that will avoid " -"conflicting with the external package manager and reduces the risk of " -"breaking software shipped by the external package manager." +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:32 -msgid "Terminology" +#: ../source/specifications/inline-script-metadata.rst:62 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:34 +#: ../source/specifications/inline-script-metadata.rst:65 msgid "" -"A few terms used in this specification have multiple meanings in the " -"contexts that it spans. For clarity, this specification uses the following " -"terms in specific ways:" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:61 -msgid "distro" +#: ../source/specifications/inline-script-metadata.rst:72 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:39 +#: ../source/specifications/inline-script-metadata.rst:75 msgid "" -"Short for \"distribution,\" a collection of various sorts of software, " -"ideally designed to work properly together, including (in contexts relevant " -"to this document) the Python interpreter itself, software written in Python, " -"and software written in other languages. That is, this is the sense used in " -"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this PEP or future ones." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:46 +#: ../source/specifications/inline-script-metadata.rst:79 +#, fuzzy +#| msgid "Project name" +msgid "pyproject type" +msgstr "專案名稱" + +#: ../source/specifications/inline-script-metadata.rst:81 msgid "" -"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " -"or FreeBSD. It can also be an overlay distribution that installs on top of " -"an existing OS, such as Homebrew or MacPorts." +"The first type of metadata block is named ``pyproject`` which represents " +"content similar to what one would see in a ``pyproject.toml`` file." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:51 -msgid "" -"This document uses the short term \"distro,\" because the term " -"\"distribution\" has another meaning in Python packaging contexts: a source " -"or binary distribution package of a single piece of Python language " -"software, that is, in the sense of ``setuptools.dist.Distribution`` or " -"\"sdist\". To avoid confusion, this document does not use the plain term " -"\"distribution\" at all. In the Python packaging sense, it uses the full " -"phrase \"distribution package\" or just \"package\" (see below)." +#: ../source/specifications/inline-script-metadata.rst:84 +msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:60 +#: ../source/specifications/inline-script-metadata.rst:86 msgid "" -"The provider of a distro - the team or company that collects and publishes " -"the software and makes any needed modifications - is its **distributor**." +"The :ref:`tool table ` MAY be used by any tool, script " +"runner or otherwise, to configure behavior." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:79 -#, fuzzy -#| msgid "Package Index" -msgid "package" -msgstr "套件索引" +#: ../source/specifications/inline-script-metadata.rst:89 +msgid "The ``[run]`` table MAY include the following optional fields:" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:64 +#: ../source/specifications/inline-script-metadata.rst:91 msgid "" -"A unit of software that can be installed and used within Python. That is, " -"this refers to what Python-specific packaging tools tend to call a :term:" -"`distribution package` or simply a \"distribution\"; the colloquial " -"abbreviation \"package\" is used in the sense of the Python Package Index." +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:70 +#: ../source/specifications/inline-script-metadata.rst:94 msgid "" -"This document does not use \"package\" in the sense of an importable name " -"that contains Python modules, though in many cases, a distribution package " -"consists of a single importable package of the same name." +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a valid :ref:" +"`version specifier `." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:75 +#: ../source/specifications/inline-script-metadata.rst:98 msgid "" -"This document generally does not use the term \"package\" to refer to units " -"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " -"files). When needed, it uses phrasing such as \"a distro's package." -"\" (Again, in many cases, a Python package is shipped inside a distro's " -"package named something like ``python-`` plus the Python package name.)" +"Any future specifications that define additional fields for the ``[run]`` " +"table when used in a ``pyproject.toml`` file MUST include the aforementioned " +"fields exactly as specified. The fields defined by this specification are " +"equally as applicable to full-fledged projects as they are to single-file " +"scripts." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:102 -#, fuzzy -#| msgid "Installing packages" -msgid "Python-specific package manager" -msgstr "安裝軟體套件" - -#: ../source/specifications/externally-managed-environments.rst:82 +#: ../source/specifications/inline-script-metadata.rst:103 msgid "" -"A tool for installing, upgrading, and/or removing Python packages in a " -"manner that conforms to Python packaging standards. The most popular Python-" -"specific package manager is pip_; other examples include the old `Easy " -"Install command `_ as well as direct usage of a ``setup.py`` " -"command." +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:92 -msgid "" -"(Note that the ``easy_install`` command was removed in setuptools version " -"52, released 23 January 2021.)" +#: ../source/specifications/inline-script-metadata.rst:108 +msgid "Example" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:96 +#: ../source/specifications/inline-script-metadata.rst:110 msgid "" -"(Conda_ is a bit of a special case, as the ``conda`` command can install " -"much more than just Python packages, making it more like a distro package " -"manager in some senses. Since the ``conda`` command generally only operates " -"on Conda-created environments, most of the concerns in this document do not " -"apply to ``conda`` when acting as a Python-specific package manager.)" +"The following is an example of a script with an embedded ``pyproject.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:118 -msgid "distro package manager" +#: ../source/specifications/inline-script-metadata.rst:130 +msgid "" +"The following is an example of a proposed syntax for single-file Rust " +"projects that embeds their equivalent of ``pyproject.toml``, which is called " +"``Cargo.toml``:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:105 +#: ../source/specifications/inline-script-metadata.rst:149 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "文件類型" + +#: ../source/specifications/inline-script-metadata.rst:151 msgid "" -"A tool for installing, upgrading, and/or removing a distro's packages in an " -"installed instance of that distro, which is capable of installing Python " -"packages as well as non-Python packages, and therefore generally has its own " -"database of installed software unrelated to the :ref:`database of installed " -"distributions `. Examples include ``apt``, " -"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " -"that if a package was installed by a distro package manager, removing or " -"upgrading it in a way that would satisfy a Python-specific package manager " -"will generally leave a distro package manager in an inconsistent state." +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:117 +#: ../source/specifications/inline-script-metadata.rst:177 msgid "" -"This document also uses phrases like \"external package manager\" or " -"\"system's package manager\" to refer to a distro package manager in certain " -"contexts." +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:127 -msgid "shadow" +#: ../source/specifications/inline-script-metadata.rst:208 +msgid "" +"Note that this example used a library that preserves TOML formatting. This " +"is not a requirement for editing by any means but rather is a \"nice to " +"have\" feature." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:121 +#: ../source/specifications/inline-script-metadata.rst:212 msgid "" -"To shadow an installed Python package is to cause some other package to be " -"preferred for imports without removing any files from the shadowed package. " -"This requires multiple entries on ``sys.path``: if package A 2.0 installs " -"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " -"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " -"from the former, and we say that A 2.0 shadows A 1.0." +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:132 -msgid "This specification is twofold." +#: ../source/specifications/inline-script-metadata.rst:231 +msgid "Recommendations" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:134 +#: ../source/specifications/inline-script-metadata.rst:233 msgid "" -"First, it describes **a way for distributors of a Python interpreter to mark " -"that interpreter as having its packages managed by means external to " -"Python**, such that Python-specific tools like pip should not change the " -"installed packages in the interpreter's global ``sys.path`` in any way (add, " -"upgrade/downgrade, or remove) unless specifically overridden. It also " -"provides a means for the distributor to indicate how to use a virtual " -"environment as an alternative." +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:142 -msgid "" -"This is an opt-in mechanism: by default, the Python interpreter compiled " -"from upstream sources will not be so marked, and so running ``pip install`` " -"with a self-compiled interpreter, or with a distro that has not explicitly " -"marked its interpreter, will work as it always has worked." +#: ../source/specifications/inline-script-metadata.rst:241 +msgid "This specification was originally defined as :pep:`723`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:148 +#: ../source/specifications/name-normalization.rst:5 +msgid "Package name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:7 msgid "" -"Second, it sets the rule that when installing packages to an interpreter's " -"global context (either to an unmarked interpreter, or if overriding the " -"marking), **Python-specific package managers should modify or delete files " -"only within the directories of the sysconfig scheme in which they would " -"create files**. This permits a distributor of a Python interpreter to set up " -"two directories, one for its own managed packages, and one for unmanaged " -"packages installed by the end user, and ensure that installing unmanaged " -"packages will not delete (or overwrite) files owned by the external package " -"manager." +"Project names are \"normalized\" for use in various contexts. This document " +"describes how project names should be normalized." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:160 -msgid "Marking an interpreter as using an external package manager" +#: ../source/specifications/name-normalization.rst:10 +msgid "Valid non-normalized names" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:162 +#: ../source/specifications/name-normalization.rst:12 msgid "" -"Before a Python-specific package installer (that is, a tool such as pip - " -"not an external tool such as apt) installs a package into a certain Python " -"context, it should make the following checks by default:" +"A valid name consists only of ASCII letters and numbers, period, underscore " +"and hyphen. It must start and end with a letter or number. This means that " +"valid project names are limited to those which match the following regex " +"(run with ``re.IGNORECASE``)::" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:167 +#: ../source/specifications/name-normalization.rst:20 +#: ../source/specifications/version-specifiers.rst:394 +#, fuzzy +msgid "Normalization" +msgstr "翻譯" + +#: ../source/specifications/name-normalization.rst:22 msgid "" -"Is it running outside of a virtual environment? It can determine this by " -"whether ``sys.prefix == sys.base_prefix``." +"The name should be lowercased with all runs of the characters ``.``, ``-``, " +"or ``_`` replaced with a single ``-`` character. This can be implemented in " +"Python with the re module:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:170 -msgid "" -"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " -"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +#: ../source/specifications/name-normalization.rst:31 +msgid "This means that the following names are all equivalent:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:173 -msgid "" -"If both of these conditions are true, the installer should exit with an " -"error message indicating that package installation into this Python " -"interpreter's directory are disabled outside of a virtual environment." +#: ../source/specifications/name-normalization.rst:33 +msgid "``friendly-bard`` (normalized form)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:177 -msgid "" -"The installer should have a way for the user to override these rules, such " -"as a command-line flag ``--break-system-packages``. This option should not " -"be enabled by default and should carry some connotation that its use is " -"risky." +#: ../source/specifications/name-normalization.rst:34 +msgid "``Friendly-Bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:182 -msgid "" -"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " -"parsable by the standard library configparser_ module. If the file can be " -"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " -"encoding, and it contains a section ``[externally-managed]``, then the " -"installer should look for an error message specified in the file and output " -"it as part of its error. If the first element of the tuple returned by " -"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " -"``None``, it should look for the error message as the value of a key named " -"``Error-`` followed by the language code. If that key does not exist, and if " -"the language code contains underscore or hyphen, it should look for a key " -"named ``Error-`` followed by the portion of the language code before the " -"underscore or hyphen. If it cannot find either of those, or if the language " -"code is ``None``, it should look for a key simply named ``Error``." +#: ../source/specifications/name-normalization.rst:35 +msgid "``FRIENDLY-BARD``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:200 -msgid "" -"If the installer cannot find an error message in the file (either because " -"the file cannot be parsed or because no suitable error key exists), then the " -"installer should just use a pre-defined error message of its own, which " -"should suggest that the user create a virtual environment to install " -"packages." +#: ../source/specifications/name-normalization.rst:36 +msgid "``friendly.bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:206 -msgid "" -"Software distributors who have a non-Python-specific package manager that " -"manages libraries in the ``sys.path`` of their Python package should, in " -"general, ship a ``EXTERNALLY-MANAGED`` file in their standard library " -"directory. For instance, Debian may ship a file in ``/usr/lib/python3.9/" -"EXTERNALLY-MANAGED`` consisting of something like" +#: ../source/specifications/name-normalization.rst:37 +msgid "``friendly_bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:230 -msgid "" -"which provides useful and distro-relevant information to a user trying to " -"install a package. Optionally, translations can be provided in the same file:" +#: ../source/specifications/name-normalization.rst:38 +msgid "``friendly--bard``" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:240 +#: ../source/specifications/name-normalization.rst:39 msgid "" -"In certain contexts, such as single-application container images that aren't " -"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" -"MANAGED`` file, so that users can install whatever they like (as they can " -"today) without having to manually override this rule." +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:247 -msgid "Writing to only the target ``sysconfig`` scheme" +#: ../source/specifications/name-normalization.rst:44 +msgid "" +"`September 2015 `_: normalized name was originally specified in :pep:" +"`503#normalized-names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:249 +#: ../source/specifications/name-normalization.rst:45 msgid "" -"Usually, a Python package installer installs to directories in a scheme " -"returned by the ``sysconfig`` standard library package. Ordinarily, this is " -"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " -"configuration (e.g. ``pip install --user``), it may use a different scheme." +"`November 2015 `_: valid non-normalized name was originally specified " +"in :pep:`508#names`." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:255 -msgid "" -"Whenever the installer is installing to a ``sysconfig`` scheme, this " -"specification declares that the installer should never modify or delete " -"files outside of that scheme. For instance, if it's upgrading a package, and " -"the package is already installed in a directory outside that scheme (perhaps " -"in a directory from another scheme), it should leave the existing files " -"alone." +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:262 +#: ../source/specifications/platform-compatibility-tags.rst:8 msgid "" -"If the installer does end up shadowing an existing installation during an " -"upgrade, we recommend that it produces a warning at the end of its run." +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:266 -msgid "" -"If the installer is installing to a location outside of a ``sysconfig`` " -"scheme (e.g., ``pip install --target``), then this subsection does not apply." +#: ../source/specifications/platform-compatibility-tags.rst:12 +msgid "The following PEPs contributed to this spec:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:271 -msgid "Recommendations for distros" +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid ":pep:`425`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:273 -msgid "" -"This section is non-normative. It provides best practices we believe distros " -"should follow unless they have a specific reason otherwise." +#: ../source/specifications/platform-compatibility-tags.rst:15 +msgid ":pep:`513`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:277 -msgid "Mark the installation as externally managed" +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid ":pep:`571`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:279 -msgid "" -"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " -"directory." +#: ../source/specifications/platform-compatibility-tags.rst:17 +msgid ":pep:`599`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:283 -msgid "Guide users towards virtual environments" +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid ":pep:`600`" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:285 -msgid "" -"The file should contain a useful and distro-relevant error message " -"indicating both how to install system-wide packages via the distro's package " -"manager and how to set up a virtual environment. If your distro is often " -"used by users in a state where the ``python3`` command is available (and " -"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " -"venv`` does not work, the message should indicate clearly how to make " -"``python3 -m venv`` work properly." +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:293 -msgid "" -"Consider packaging pipx_, a tool for installing Python-language " -"applications, and suggesting it in the error. pipx automatically creates a " -"virtual environment for that application alone, which is a much better " -"default for end users who want to install some Python-language software " -"(which isn't available in the distro) but are not themselves Python users. " -"Packaging pipx in the distro avoids the irony of instructing users to ``pip " -"install --user --break-system-packages pipx`` to *avoid* breaking system " -"packages. Consider arranging things so your distro's package / environment " -"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " -"Debian) depends on pipx." +#: ../source/specifications/platform-compatibility-tags.rst:25 +msgid "python tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:308 -msgid "Keep the marker file in container images" +#: ../source/specifications/platform-compatibility-tags.rst:26 +msgid "'py27', 'cp33'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:310 -msgid "" -"Distros that produce official images for single-application containers (e." -"g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " -"preferably in a way that makes it not go away if a user of that image " -"installs package updates inside their image (think ``RUN apt-get dist-" -"upgrade``)." +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "'cp32dmu', 'none'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:317 -msgid "Create separate distro and local directories" +#: ../source/specifications/platform-compatibility-tags.rst:30 +msgid "'linux_x86_64', 'any'" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:319 +#: ../source/specifications/platform-compatibility-tags.rst:32 msgid "" -"Distros should place two separate paths on the system interpreter's ``sys." -"path``, one for distro-installed packages and one for packages installed by " -"the local system administrator, and configure ``sysconfig." -"get_default_scheme()`` to point at the latter path. This ensures that tools " -"like pip will not modify distro-installed packages. The path for the local " -"system administrator should come before the distro path on ``sys.path`` so " -"that local installs take preference over distro packages." +"For example, the tag ``py27-none-any`` indicates compatibility with Python " +"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:328 -msgid "" -"For example, Fedora and Debian (and their derivatives) both implement this " -"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " -"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" -"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" -"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " -"an additional layer of separation from a locally-compiled Python " -"interpreter: if you build and install upstream CPython in ``/usr/local/" -"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " -"wishes to make sure that packages installed via the locally-built " -"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +#: ../source/specifications/platform-compatibility-tags.rst:36 +#: ../source/specifications/platform-compatibility-tags.rst:170 +msgid "Use" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:341 +#: ../source/specifications/platform-compatibility-tags.rst:38 msgid "" -"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " -"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " -"and non-distro software installs to ``/usr/local`` by default. This split is " -"`recommended by the Filesystem Hierarchy Standard`__." +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:349 -msgid "" -"There are two ways you could do this. One is, if you are building and " -"packaging Python libraries directly (e.g., your packaging helpers unpack a " -"wheel or call ``setup.py install``), arrange for those tools to use a " -"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "Any potential spaces in any tag should be replaced with ``_``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:355 -msgid "" -"The other is to arrange for the default ``sysconfig`` scheme to change when " -"running inside a package build versus when running on an installed system. " -"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " -"(once accepted and implemented): make your packaging tool set an environment " -"variable or some other detectable configuration, and define a " -"``get_preferred_schemes`` function to return a different scheme when called " -"from inside a package build. Then you can use ``pip install`` as part of " -"your distro packaging." +#: ../source/specifications/platform-compatibility-tags.rst:49 +msgid "Python Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:367 +#: ../source/specifications/platform-compatibility-tags.rst:51 msgid "" -"We propose adding a ``--scheme=...`` option to instruct pip to run against a " -"specific scheme. (See `Implementation Notes`_ below for how pip currently " -"determines schemes.) Once that's available, for local testing and possibly " -"for actual packaging, you would be able to run something like ``pip install " -"--scheme=posix_distro`` to explicitly install a package into your distro's " -"location (bypassing ``get_preferred_schemes``). One could also, if " -"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " -"remove packages from the system-managed directory." +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:377 -msgid "" -"To install packages with pip, you would also need to either suppress the " -"``EXTERNALLY-MANAGED`` marker file to allow pip to run or to override it on " -"the command line. You may want to use the same means for suppressing the " -"marker file in build chroots as you do in container images." +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "py: Generic Python (does not require implementation-specific features)" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:383 -msgid "" -"The advantage of setting these up to be automatic (suppressing the marker " -"file in your build environment and having ``get_preferred_schemes`` " -"automatically return your distro's scheme) is that an unadorned ``pip " -"install`` will work inside a package build, which generally means that an " -"unmodified upstream build script that happens to internally call ``pip " -"install`` will do the right thing. You can, of course, just ensure that your " -"packaging process always calls ``pip install --scheme=posix_distro --break-" -"system-packages``, which would work too." +#: ../source/specifications/platform-compatibility-tags.rst:55 +msgid "cp: CPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:393 -msgid "" -"The best approach here depends a lot on your distro's conventions and " -"mechanisms for packaging." +#: ../source/specifications/platform-compatibility-tags.rst:56 +msgid "ip: IronPython" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:396 -msgid "" -"Similarly, the ``sysconfig`` paths that are not for importable Python code - " -"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " -"also have two variants, one for use by distro-packaged software and one for " -"use for locally-installed software, and the distro should be set up such " -"that both are usable. For instance, a typical FHS-compliant distro will use " -"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" -"include`` for distro-packaged headers and place both on the compiler's " -"search path, and it will use ``/usr/local/bin`` for the default scheme's " -"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " -"on ``$PATH``." +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "pp: PyPy" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:410 -#, fuzzy -#| msgid "Documentation types" -msgid "Implementation Notes" -msgstr "文件類型" +#: ../source/specifications/platform-compatibility-tags.rst:58 +msgid "jy: Jython" +msgstr "" -#: ../source/specifications/externally-managed-environments.rst:412 -msgid "" -"This section is non-normative and contains notes relevant to both the " -"specification and potential implementations." +#: ../source/specifications/platform-compatibility-tags.rst:60 +msgid "Other Python implementations should use ``sys.implementation.name``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:415 +#: ../source/specifications/platform-compatibility-tags.rst:62 msgid "" -"Currently (as of May 2021), pip does not directly expose a way to choose a " -"target ``sysconfig`` scheme, but it has three ways of looking up schemes " -"when installing:" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:422 -msgid "``pip install``" +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:420 +#: ../source/specifications/platform-compatibility-tags.rst:69 msgid "" -"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " -"CPython and most current distros) the same as " -"``get_preferred_scheme('prefix')``." +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "``pip install --prefix=/some/path``" +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:425 -msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +#: ../source/specifications/platform-compatibility-tags.rst:77 +msgid "ABI Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "``pip install --user``" +#: ../source/specifications/platform-compatibility-tags.rst:79 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:428 -msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +#: ../source/specifications/platform-compatibility-tags.rst:84 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:430 +#: ../source/specifications/platform-compatibility-tags.rst:86 msgid "" -"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" -"path`` without looking up any schemes." +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:433 -msgid "" -"Debian currently carries a `patch to change the default install location " -"inside a virtual environment`__, using a few heuristics (including checking " -"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " -"used in a virtual environment remains ``site-packages`` and not ``dist-" -"packages``. This does not particularly affect this proposal, because the " -"implementation of that patch does not actually change the default " -"``sysconfig`` scheme, and notably does not change the result of ``sysconfig." -"get_path(\"stdlib\")``." +#: ../source/specifications/platform-compatibility-tags.rst:93 +msgid "Platform Tag" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:445 +#: ../source/specifications/platform-compatibility-tags.rst:95 msgid "" -"Fedora currently carries a `patch to change the default install location " -"when not running inside rpmbuild`__, which they use to implement the two-" -"system-wide-directories approach. This is conceptually the sort of hook " -"envisioned by bpo-43976_, except implemented as a code patch to " -"``distutils`` instead of as a changed ``sysconfig`` scheme." +"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" +"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" +"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." msgstr "" -#: ../source/specifications/externally-managed-environments.rst:454 -msgid "" -"The implementation of ``is_virtual_environment`` above, as well as the logic " -"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " -"may as well get added to the standard library (``sys`` and ``sysconfig``, " -"respectively), to centralize their implementations, but they don't need to " -"be added yet." +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "win32" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:466 -msgid "" -"This document is placed in the public domain or under the CC0-1.0-Universal " -"license, whichever is more permissive." +#: ../source/specifications/platform-compatibility-tags.rst:101 +msgid "linux_i386" msgstr "" -#: ../source/specifications/externally-managed-environments.rst:474 -msgid "This specification was originally approved as :pep:`668`." +#: ../source/specifications/platform-compatibility-tags.rst:102 +msgid "linux_x86_64" msgstr "" -#: ../source/specifications/index.rst:4 -msgid "PyPA specifications" +#: ../source/specifications/platform-compatibility-tags.rst:107 +#, fuzzy +msgid "``manylinux``" +msgstr "維護者" + +#: ../source/specifications/platform-compatibility-tags.rst:110 +msgid "" +"The scheme defined in :pep:`425` was insufficient for public distribution of " +"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " +"the large ecosystem of Linux platforms and subtle differences between them." msgstr "" -#: ../source/specifications/index.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:114 msgid "" -"This is a list of currently active interoperability specifications " -"maintained by the Python Packaging Authority. The process for updating these " -"standards, and for proposing new ones, is documented on `pypa.io `__." +"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " +"common subset of Linux platforms, and allows building wheels tagged with the " +"``manylinux`` platform tag which can be used across most common Linux " +"distributions." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:3 -msgid "Inline script metadata" +#: ../source/specifications/platform-compatibility-tags.rst:119 +msgid "" +"There were multiple iterations of the ``manylinux`` specification, each " +"representing the common subset of Linux platforms at a given point in time:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:6 +#: ../source/specifications/platform-compatibility-tags.rst:122 msgid "" -"This specification has been **provisionally accepted**. It is subject to " -"being changed or abandoned. See the `PEP 723 conditional acceptance thread " -"`_ for details." +"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " +"and is based on a compatible Linux platform from 2007." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:12 +#: ../source/specifications/platform-compatibility-tags.rst:124 msgid "" -"This specification defines a metadata format that can be embedded in single-" -"file Python scripts to assist launchers, IDEs and other external tools which " -"may need to interact with such scripts." +"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +"architectures. and updates the previous specification to be based on a " +"compatible Linux platform from 2010 instead." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:20 +#: ../source/specifications/platform-compatibility-tags.rst:127 msgid "" -"This specification defines a metadata comment block format (loosely inspired " -"by `reStructuredText Directives`__)." +"``manylinux2014`` (:pep:`599`) adds support for a number of additional " +"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +"``s390x``) and updates the base platform to a compatible Linux platform from " +"2014." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:25 +#: ../source/specifications/platform-compatibility-tags.rst:132 msgid "" -"Any Python script may have top-level comment blocks that MUST start with the " -"line ``# /// TYPE`` where ``TYPE`` determines how to process the content. " -"That is: a single ``#``, followed by a single space, followed by three " -"forward slashes, followed by a single space, followed by the type of " -"metadata. Block MUST end with the line ``# ///``. That is: a single ``#``, " -"followed by a single space, followed by three forward slashes. The ``TYPE`` " -"MUST only consist of ASCII letters, numbers and hyphens." +"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " +"glibc 2.24+). Previous tags are still supported for backward compatibility." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:33 +#: ../source/specifications/platform-compatibility-tags.rst:137 msgid "" -"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " -"comment starting with ``#``. If there are characters after the ``#`` then " -"the first character MUST be a space. The embedded content is formed by " -"taking away the first two characters of each line if the second character is " -"a space, otherwise just the first character (which means the line consists " -"of only a single ``#``)." +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:40 +#: ../source/specifications/platform-compatibility-tags.rst:143 msgid "" -"Precedence for an ending line ``# ///`` is given when the next line is not a " -"valid embedded content line as described above. For example, the following " -"is a single fully valid block:" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:56 -msgid "" -"A starting line MUST NOT be placed between another starting line and its " -"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " -"be ignored." +#: ../source/specifications/platform-compatibility-tags.rst:149 +msgid "Manylinux compatibility support" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:59 +#: ../source/specifications/platform-compatibility-tags.rst:152 msgid "" -"When there are multiple comment blocks of the same ``TYPE`` defined, tools " -"MUST produce an error." +"The ``manylinux2014`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:62 +#: ../source/specifications/platform-compatibility-tags.rst:154 msgid "" -"Tools reading embedded metadata MAY respect the standard Python encoding " -"declaration. If they choose not to do so, they MUST process the file as " -"UTF-8." +"The ``manylinux_x_y`` specification is relatively new and is not yet widely " +"recognised by install tools." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:65 +#: ../source/specifications/platform-compatibility-tags.rst:157 msgid "" -"This is the canonical regular expression that MAY be used to parse the " -"metadata:" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:72 -msgid "" -"In circumstances where there is a discrepancy between the text specification " -"and the regular expression, the text specification takes precedence." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "Tool" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:75 -msgid "" -"Tools MUST NOT read from metadata blocks with types that have not been " -"standardized by this PEP or future ones." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux1``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:79 -#, fuzzy -#| msgid "Project name" -msgid "pyproject type" -msgstr "專案名稱" +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2010``" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:81 -msgid "" -"The first type of metadata block is named ``pyproject`` which represents " -"content similar to what one would see in a ``pyproject.toml`` file." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux2014``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:84 -msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#: ../source/specifications/platform-compatibility-tags.rst:161 +msgid "``manylinux_x_y``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:86 -msgid "" -"The :ref:`tool table ` MAY be used by any tool, script " -"runner or otherwise, to configure behavior." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=8.1.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:89 -msgid "The ``[run]`` table MAY include the following optional fields:" +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:91 -msgid "" -"``dependencies``: A list of strings that specifies the runtime dependencies " -"of the script. Each entry MUST be a valid :ref:`dependency specifier " -"`." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=19.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:94 -msgid "" -"``requires-python``: A string that specifies the Python version(s) with " -"which the script is compatible. The value of this field MUST be a valid :ref:" -"`version specifier `." +#: ../source/specifications/platform-compatibility-tags.rst:163 +msgid "``>=20.3``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:98 -msgid "" -"Any future specifications that define additional fields for the ``[run]`` " -"table when used in a ``pyproject.toml`` file MUST include the aforementioned " -"fields exactly as specified. The fields defined by this specification are " -"equally as applicable to full-fledged projects as they are to single-file " -"scripts." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "auditwheel" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:103 -msgid "" -"Script runners MUST error if the specified ``dependencies`` cannot be " -"provided. Script runners SHOULD error if no version of Python that satisfies " -"the specified ``requires-python`` can be provided." +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=1.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:108 -msgid "Example" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=2.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:110 -msgid "" -"The following is an example of a script with an embedded ``pyproject.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.0.0``" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:130 -msgid "" -"The following is an example of a proposed syntax for single-file Rust " -"projects that embeds their equivalent of ``pyproject.toml``, which is called " -"``Cargo.toml``:" +#: ../source/specifications/platform-compatibility-tags.rst:164 +msgid "``>=3.3.0`` [#]_" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:149 -#, fuzzy -#| msgid "Documentation types" -msgid "Reference Implementation" -msgstr "文件類型" +#: ../source/specifications/platform-compatibility-tags.rst:167 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" -#: ../source/specifications/inline-script-metadata.rst:151 +#: ../source/specifications/platform-compatibility-tags.rst:172 msgid "" -"The following is an example of how to read the metadata on Python 3.11 or " -"higher." +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:177 +#: ../source/specifications/platform-compatibility-tags.rst:178 msgid "" -"Often tools will edit dependencies like package managers or dependency " -"update automation in CI. The following is a crude example of modifying the " -"content using the ``tomlkit`` library__." +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:208 +#: ../source/specifications/platform-compatibility-tags.rst:186 msgid "" -"Note that this example used a library that preserves TOML formatting. This " -"is not a requirement for editing by any means but rather is a \"nice to " -"have\" feature." +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." msgstr "" -#: ../source/specifications/inline-script-metadata.rst:212 +#: ../source/specifications/platform-compatibility-tags.rst:190 msgid "" -"The following is an example of how to read a stream of arbitrary metadata " -"blocks." +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:231 -msgid "Recommendations" +#: ../source/specifications/platform-compatibility-tags.rst:196 +msgid "cp33-cp33m-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:233 -msgid "" -"Tools that support managing different versions of Python should attempt to " -"use the highest available version of Python that is compatible with the " -"script's ``requires-python`` metadata, if defined." +#: ../source/specifications/platform-compatibility-tags.rst:197 +msgid "cp33-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/inline-script-metadata.rst:241 -msgid "This specification was originally defined as :pep:`723`." +#: ../source/specifications/platform-compatibility-tags.rst:198 +msgid "cp3-abi3-linux_x86_64" msgstr "" -#: ../source/specifications/name-normalization.rst:5 -msgid "Package name normalization" +#: ../source/specifications/platform-compatibility-tags.rst:199 +msgid "cp33-none-linux_x86_64*" msgstr "" -#: ../source/specifications/name-normalization.rst:7 -msgid "" -"Project names are \"normalized\" for use in various contexts. This document " -"describes how project names should be normalized." +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:201 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:203 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:204 +msgid "cp3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:10 -msgid "Valid non-normalized names" +#: ../source/specifications/platform-compatibility-tags.rst:205 +msgid "py33-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:12 -msgid "" -"A valid name consists only of ASCII letters and numbers, period, underscore " -"and hyphen. It must start and end with a letter or number. This means that " -"valid project names are limited to those which match the following regex " -"(run with ``re.IGNORECASE``)::" +#: ../source/specifications/platform-compatibility-tags.rst:206 +msgid "py3-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:20 -#: ../source/specifications/version-specifiers.rst:392 -#, fuzzy -msgid "Normalization" -msgstr "翻譯" +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "py32-none-any" +msgstr "" -#: ../source/specifications/name-normalization.rst:22 -msgid "" -"The name should be lowercased with all runs of the characters ``.``, ``-``, " -"or ``_`` replaced with a single ``-`` character. This can be implemented in " -"Python with the re module:" +#: ../source/specifications/platform-compatibility-tags.rst:208 +msgid "py31-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:31 -msgid "This means that the following names are all equivalent:" +#: ../source/specifications/platform-compatibility-tags.rst:209 +msgid "py30-none-any" msgstr "" -#: ../source/specifications/name-normalization.rst:33 -msgid "``friendly-bard`` (normalized form)" +#: ../source/specifications/platform-compatibility-tags.rst:211 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." msgstr "" -#: ../source/specifications/name-normalization.rst:34 -msgid "``Friendly-Bard``" +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." msgstr "" -#: ../source/specifications/name-normalization.rst:35 -msgid "``FRIENDLY-BARD``" +#: ../source/specifications/platform-compatibility-tags.rst:224 +msgid "Compressed Tag Sets" msgstr "" -#: ../source/specifications/name-normalization.rst:36 -msgid "``friendly.bard``" +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "" +"To allow for compact filenames of bdists that work with more than one " +"compatibility tag triple, each tag in a filename can instead be a '.'-" +"separated, sorted, set of tags. For example, pip, a pure-Python package " +"that is written to run under Python 2 and 3 with the same source code, could " +"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " +"simple tags is::" msgstr "" -#: ../source/specifications/name-normalization.rst:37 -msgid "``friendly_bard``" +#: ../source/specifications/platform-compatibility-tags.rst:238 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." msgstr "" -#: ../source/specifications/name-normalization.rst:38 -msgid "``friendly--bard``" +#: ../source/specifications/platform-compatibility-tags.rst:251 +msgid "What tags are used by default?" msgstr "" -#: ../source/specifications/name-normalization.rst:39 +#: ../source/specifications/platform-compatibility-tags.rst:247 msgid "" -"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." msgstr "" -#: ../source/specifications/name-normalization.rst:44 +#: ../source/specifications/platform-compatibility-tags.rst:261 msgid "" -"`September 2015 `_: normalized name was originally specified in :pep:" -"`503#normalized-names`." +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" msgstr "" -#: ../source/specifications/name-normalization.rst:45 +#: ../source/specifications/platform-compatibility-tags.rst:254 msgid "" -"`November 2015 `_: valid non-normalized name was originally specified " -"in :pep:`508#names`." +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:6 -msgid "Platform compatibility tags" +#: ../source/specifications/platform-compatibility-tags.rst:266 +msgid "Why isn't there a ``.`` in the Python version number?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:8 +#: ../source/specifications/platform-compatibility-tags.rst:264 msgid "" -"Platform compatibility tags allow build tools to mark distributions as being " -"compatible with specific platforms, and allows installers to understand " -"which distributions are compatible with the system they are running on." +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:12 -msgid "The following PEPs contributed to this spec:" +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:14 -msgid ":pep:`425`" +#: ../source/specifications/platform-compatibility-tags.rst:269 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:15 -msgid ":pep:`513`" +#: ../source/specifications/platform-compatibility-tags.rst:281 +msgid "Why not use special character rather than ``.`` or ``-``?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:16 -msgid ":pep:`571`" +#: ../source/specifications/platform-compatibility-tags.rst:275 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:17 -msgid ":pep:`599`" +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "Who will maintain the registry of abbreviated implementations?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:18 -msgid ":pep:`600`" +#: ../source/specifications/platform-compatibility-tags.rst:284 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:23 -msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +#: ../source/specifications/platform-compatibility-tags.rst:291 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:25 -msgid "python tag" +#: ../source/specifications/platform-compatibility-tags.rst:289 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:26 -msgid "'py27', 'cp33'" +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "Why didn't you mention my favorite Python implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:28 -msgid "'cp32dmu', 'none'" +#: ../source/specifications/platform-compatibility-tags.rst:294 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:30 -msgid "'linux_x86_64', 'any'" +#: ../source/specifications/platform-compatibility-tags.rst:303 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:32 +#: ../source/specifications/platform-compatibility-tags.rst:300 msgid "" -"For example, the tag ``py27-none-any`` indicates compatibility with Python " -"2.7 (any Python 2.7 implementation) with no abi requirement, on any platform." +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:36 -#: ../source/specifications/platform-compatibility-tags.rst:170 -msgid "Use" +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:38 +#: ../source/specifications/pypirc.rst:8 msgid "" -"The ``wheel`` built package format includes these tags in its filenames, of " -"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" -"{platform tag}.whl``. Other package formats may have their own conventions." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:43 -msgid "Any potential spaces in any tag should be replaced with ``_``." +"A :file:`.pypirc` file allows you to define the configuration for :term:" +"`package indexes ` (referred to here as \"repositories\"), so " +"that you don't have to enter the URL, username, or password whenever you " +"upload a package with :ref:`twine` or :ref:`flit`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:49 -msgid "Python Tag" +#: ../source/specifications/pypirc.rst:13 +msgid "The format (originally defined by the :ref:`distutils` package) is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:51 +#: ../source/specifications/pypirc.rst:32 msgid "" -"The Python tag indicates the implementation and version required by a " -"distribution. Major implementations have abbreviated codes, initially:" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:54 -msgid "py: Generic Python (does not require implementation-specific features)" +#: ../source/specifications/pypirc.rst:35 +msgid "Each section describing a repository defines three fields:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:55 -msgid "cp: CPython" +#: ../source/specifications/pypirc.rst:37 +msgid "``repository``: The URL of the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:56 -msgid "ip: IronPython" +#: ../source/specifications/pypirc.rst:38 +msgid "``username``: The registered username on the repository." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:57 -msgid "pp: PyPy" +#: ../source/specifications/pypirc.rst:39 +msgid "``password``: The password that will used to authenticate the username." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:58 -msgid "jy: Jython" +#: ../source/specifications/pypirc.rst:43 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:60 -msgid "Other Python implementations should use ``sys.implementation.name``." +#: ../source/specifications/pypirc.rst:47 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:62 -msgid "" -"The version is ``py_version_nodot``. CPython gets away with no dot, but if " -"one is needed the underscore ``_`` is used instead. PyPy should probably " -"use its own versions here ``pp18``, ``pp19``." +#: ../source/specifications/pypirc.rst:57 +msgid "Common configurations" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:66 +#: ../source/specifications/pypirc.rst:61 msgid "" -"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " -"for many pure-Python distributions." +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:69 +#: ../source/specifications/pypirc.rst:65 msgid "" -"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " -"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " -"intentionally released a cross-version-compatible distribution." +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:73 +#: ../source/specifications/pypirc.rst:81 msgid "" -"A single-source Python 2/3 compatible distribution can use the compound tag " -"``py2.py3``. See `Compressed Tag Sets`_, below." +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:77 -msgid "ABI Tag" +#: ../source/specifications/pypirc.rst:85 +msgid "Using a PyPI token" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:79 +#: ../source/specifications/pypirc.rst:87 msgid "" -"The ABI tag indicates which Python ABI is required by any included extension " -"modules. For implementation-specific ABIs, the implementation is " -"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " -"CPython 3.3 ABI with debugging." -msgstr "" - -#: ../source/specifications/platform-compatibility-tags.rst:84 -msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:86 +#: ../source/specifications/pypirc.rst:96 msgid "" -"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " -"base64-encoded characters) of the SHA-256 hash of their source code revision " -"and compiler flags, etc, but will probably not have a great need to " -"distribute binary distributions. Each implementation's community may decide " -"how to best use the ABI tag." +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:93 -msgid "Platform Tag" +#: ../source/specifications/pypirc.rst:102 +msgid "Using another package index" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:95 +#: ../source/specifications/pypirc.rst:104 msgid "" -"The platform tag is simply ``sysconfig.get_platform()`` with all hyphens ``-" -"`` and periods ``.`` replaced with underscore ``_``. Until the removal of :" -"ref:`distutils` in Python 3.12, this was ``distutils.util.get_platform()``." +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:100 -msgid "win32" +#: ../source/specifications/pypirc.rst:131 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:101 -msgid "linux_i386" +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:102 -msgid "linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:107 -#, fuzzy -msgid "``manylinux``" -msgstr "維護者" - -#: ../source/specifications/platform-compatibility-tags.rst:110 +#: ../source/specifications/pyproject-toml.rst:14 msgid "" -"The scheme defined in :pep:`425` was insufficient for public distribution of " -"wheel files (and \\*nix wheel files in general) to Linux platforms, due to " -"the large ecosystem of Linux platforms and subtle differences between them." +"The ``pyproject.toml`` file acts as a configuration file for packaging-" +"related tools (as well as other tools)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:114 -msgid "" -"Instead, :pep:`600` defines the ``manylinux`` standard, which represents a " -"common subset of Linux platforms, and allows building wheels tagged with the " -"``manylinux`` platform tag which can be used across most common Linux " -"distributions." +#: ../source/specifications/pyproject-toml.rst:17 +msgid "This specification was originally defined in :pep:`518` and :pep:`621`." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:119 +#: ../source/specifications/pyproject-toml.rst:19 msgid "" -"There were multiple iterations of the ``manylinux`` specification, each " -"representing the common subset of Linux platforms at a given point in time:" +"The ``pyproject.toml`` file is written in `TOML `_. Three " +"tables are currently specified, namely :ref:`[build-system] `, :ref:`[project] ` and :ref:`[tool] " +"`. Other tables are reserved for future use (tool-" +"specific configuration should use the ``[tool]`` table)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:122 -msgid "" -"``manylinux1`` (:pep:`513`) supports ``x86_64`` and ``i686`` architectures, " -"and is based on a compatible Linux platform from 2007." +#: ../source/specifications/pyproject-toml.rst:29 +msgid "Declaring build system dependencies: the ``[build-system]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:124 +#: ../source/specifications/pyproject-toml.rst:31 msgid "" -"``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " -"architectures. and updates the previous specification to be based on a " -"compatible Linux platform from 2010 instead." +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:127 +#: ../source/specifications/pyproject-toml.rst:37 msgid "" -"``manylinux2014`` (:pep:`599`) adds support for a number of additional " -"architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " -"``s390x``) and updates the base platform to a compatible Linux platform from " -"2014." +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:132 +#: ../source/specifications/pyproject-toml.rst:44 msgid "" -"``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " -"future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " -"versions supported (e.g. ``manylinux_2_24`` should work on any distro using " -"glibc 2.24+). Previous tags are still supported for backward compatibility." +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:137 +#: ../source/specifications/pyproject-toml.rst:53 msgid "" -"In general, distributions built for older versions of the specification are " -"forwards-compatible (meaning that ``manylinux1`` distributions should " -"continue to work on modern systems) but not backwards-compatible (meaning " -"that ``manylinux2010`` distributions are not expected to work on platforms " -"that existed before 2010)." +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:143 +#: ../source/specifications/pyproject-toml.rst:56 msgid "" -"Package maintainers should attempt to target the most compatible " -"specification possible, with the caveat that the provided build environment " -"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " -"that these images will no longer receive security updates." +"Tools should not require the existence of the ``[build-system]`` table. A " +"``pyproject.toml`` file may be used to store configuration details other " +"than build-related data and thus lack a ``[build-system]`` table " +"legitimately. If the file exists but is lacking the ``[build-system]`` table " +"then the default values as specified above should be used. If the table is " +"specified but is missing required fields then the tool should consider it an " +"error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:149 -msgid "Manylinux compatibility support" +#: ../source/specifications/pyproject-toml.rst:65 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:152 -msgid "" -"The ``manylinux2014`` specification is relatively new and is not yet widely " -"recognised by install tools." +#: ../source/specifications/pyproject-toml.rst:103 +msgid "Declaring project metadata: the ``[project]`` table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:154 +#: ../source/specifications/pyproject-toml.rst:105 msgid "" -"The ``manylinux_x_y`` specification is relatively new and is not yet widely " -"recognised by install tools." +"The ``[project]`` table specifies the project's :ref:`core metadata `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:157 +#: ../source/specifications/pyproject-toml.rst:107 msgid "" -"The following table shows the minimum versions of relevant projects to " -"support the various ``manylinux`` standards:" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "Tool" +#: ../source/specifications/pyproject-toml.rst:115 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux1``" +#: ../source/specifications/pyproject-toml.rst:118 +msgid "The only keys required to be statically defined are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2010``" +#: ../source/specifications/pyproject-toml.rst:122 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux2014``" +#: ../source/specifications/pyproject-toml.rst:127 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:161 -msgid "``manylinux_x_y``" +#: ../source/specifications/pyproject-toml.rst:130 +msgid "The complete list of keys allowed in the ``[project]`` table are:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=8.1.0``" +#: ../source/specifications/pyproject-toml.rst:132 +msgid "``authors``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.0``" +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=19.3``" +#: ../source/specifications/pyproject-toml.rst:136 +#: ../source/specifications/pyproject-toml.rst:384 +msgid "``dynamic``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:163 -msgid "``>=20.3``" +#: ../source/specifications/pyproject-toml.rst:137 +msgid "``entry-points``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "auditwheel" +#: ../source/specifications/pyproject-toml.rst:138 +msgid "``gui-scripts``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=1.0.0``" -msgstr "" +#: ../source/specifications/pyproject-toml.rst:141 +#, fuzzy +msgid "``maintainers``" +msgstr "維護者" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=2.0.0``" +#: ../source/specifications/pyproject-toml.rst:143 +msgid "``optional-dependencies``" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.0.0``" +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +#: ../source/specifications/pyproject-toml.rst:179 +#: ../source/specifications/pyproject-toml.rst:228 +msgid "TOML_ type: string" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:164 -msgid "``>=3.3.0`` [#]_" +#: ../source/specifications/pyproject-toml.rst:155 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:167 -msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +#: ../source/specifications/pyproject-toml.rst:158 +msgid "The name of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:172 +#: ../source/specifications/pyproject-toml.rst:160 msgid "" -"The tags are used by installers to decide which built distribution (if any) " -"to download from a list of potential built distributions. The installer " -"maintains a list of (pyver, abi, arch) tuples that it will support. If the " -"built distribution's tag is ``in`` the list, then it can be installed." +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:178 +#: ../source/specifications/pyproject-toml.rst:167 msgid "" -"It is recommended that installers try to choose the most feature complete " -"built distribution available (the one most specific to the installation " -"environment) by default before falling back to pure Python versions " -"published for older Python releases. Installers are also recommended to " -"provide a way to configure and re-order the list of allowed compatibility " -"tags; for example, a user might accept only the ``*-none-any`` tags to only " -"download built packages that advertise themselves as being pure Python." +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:186 +#: ../source/specifications/pyproject-toml.rst:170 msgid "" -"Another desirable installer feature might be to include \"re-compile from " -"source if possible\" as more preferable than some of the compatible but " -"legacy pre-built options." +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:190 -msgid "" -"This example list is for an installer running under CPython 3.3 on a " -"linux_x86_64 system. It is in order from most-preferred (a distribution with " -"a compiled extension module, built for the current version of Python) to " -"least-preferred (a pure-Python distribution built with an older version of " -"Python):" +#: ../source/specifications/pyproject-toml.rst:173 +msgid "Users SHOULD prefer to specify already-normalized versions." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:196 -msgid "cp33-cp33m-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:197 -msgid "cp33-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:183 +msgid "The summary description of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:198 -msgid "cp3-abi3-linux_x86_64" +#: ../source/specifications/pyproject-toml.rst:189 +msgid "TOML_ type: string or table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:199 -msgid "cp33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:190 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:200 -msgid "cp3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:194 +msgid "The full description of the project (i.e. the README)." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:201 -msgid "py33-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:196 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:202 -msgid "py3-none-linux_x86_64*" +#: ../source/specifications/pyproject-toml.rst:207 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:203 -msgid "cp33-none-any" +#: ../source/specifications/pyproject-toml.rst:214 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:204 -msgid "cp3-none-any" +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:205 -msgid "py33-none-any" +#: ../source/specifications/pyproject-toml.rst:232 +msgid "The Python version requirements of the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:206 -msgid "py3-none-any" +#: ../source/specifications/pyproject-toml.rst:238 +msgid "TOML_ type: table" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:207 -msgid "py32-none-any" +#: ../source/specifications/pyproject-toml.rst:239 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:208 -msgid "py31-none-any" +#: ../source/specifications/pyproject-toml.rst:242 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to ``pyproject.toml`` to the file which contains the " +"license for the project. Tools MUST assume the file's encoding is UTF-8. The " +"``text`` key has a string value which is the license of the project. These " +"keys are mutually exclusive, so a tool MUST raise an error if the metadata " +"specifies both keys." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:209 -msgid "py30-none-any" +#: ../source/specifications/pyproject-toml.rst:253 +msgid "TOML_ type: Array of inline tables with string keys and values" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:211 +#: ../source/specifications/pyproject-toml.rst:254 msgid "" -"Built distributions may be platform specific for reasons other than C " -"extensions, such as by including a native executable invoked as a subprocess." +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:" +"`Maintainer `, and :ref:`Maintainer-email `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:215 +#: ../source/specifications/pyproject-toml.rst:260 msgid "" -"Sometimes there will be more than one supported built distribution for a " -"particular version of a package. For example, a packager could release a " -"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " -"extension and the same distribution tagged ``py3-none-any`` that does not. " -"The index of the tag in the supported tags list breaks the tie, and the " -"package with the C extension is installed in preference to the package " -"without because that tag appears first in the list." +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:224 -msgid "Compressed Tag Sets" +#: ../source/specifications/pyproject-toml.rst:265 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:226 +#: ../source/specifications/pyproject-toml.rst:268 msgid "" -"To allow for compact filenames of bdists that work with more than one " -"compatibility tag triple, each tag in a filename can instead be a '.'-" -"separated, sorted, set of tags. For example, pip, a pure-Python package " -"that is written to run under Python 2 and 3 with the same source code, could " -"distribute a bdist with the tag ``py2.py3-none-any``. The full list of " -"simple tags is::" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:238 +#: ../source/specifications/pyproject-toml.rst:275 msgid "" -"A bdist format that implements this scheme should include the expanded tags " -"in bdist-specific metadata. This compression scheme can generate large " -"numbers of unsupported tags and \"impossible\" tags that are supported by no " -"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +"Using the data to fill in :ref:`core metadata ` is as follows:" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:251 -msgid "What tags are used by default?" +#: ../source/specifications/pyproject-toml.rst:278 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:247 +#: ../source/specifications/pyproject-toml.rst:281 msgid "" -"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" -"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " -"by default. If the packager overrides the default it indicates that they " -"intended to provide cross-Python compatibility." +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:261 +#: ../source/specifications/pyproject-toml.rst:285 msgid "" -"What tag do I use if my distribution uses a feature exclusive to the newest " -"version of Python?" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:254 -msgid "" -"Compatibility tags aid installers in selecting the *most compatible* build " -"of a *single version* of a distribution. For example, when there is no " -"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " -"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " -"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " -"as a requirement for the older release ``beaglevote-1.1.0`` that does not " -"use the new feature, to get a compatible build." +#: ../source/specifications/pyproject-toml.rst:289 +msgid "Multiple values should be separated by commas." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:266 -msgid "Why isn't there a ``.`` in the Python version number?" +#: ../source/specifications/pyproject-toml.rst:295 +#: ../source/specifications/pyproject-toml.rst:305 +msgid "TOML_ type: array of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:264 +#: ../source/specifications/pyproject-toml.rst:296 msgid "" -"CPython has lasted 20+ years without a 3-digit major release. This should " -"continue for some time. Other implementations may use _ as a delimiter, " -"since both - and . delimit the surrounding filename." +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:272 -msgid "" -"Why normalise hyphens and other non-alphanumeric characters to underscores?" +#: ../source/specifications/pyproject-toml.rst:299 +msgid "The keywords for the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:269 +#: ../source/specifications/pyproject-toml.rst:306 msgid "" -"To avoid conflicting with the ``.`` and ``-`` characters that separate " -"components of the filename, and for better compatibility with the widest " -"range of filesystem limitations for filenames (including being usable in URL " -"paths without quoting)." +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:281 -msgid "Why not use special character rather than ``.`` or ``-``?" +#: ../source/specifications/pyproject-toml.rst:309 +msgid "Trove classifiers which apply to the project." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:275 -msgid "" -"Either because that character is inconvenient or potentially confusing in " -"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " -"denote the user's home directory in POSIX), or because the advantages " -"weren't sufficiently compelling to justify changing the existing reference " -"implementation for the wheel format defined in :pep:`427` (for example, " -"using ``,`` rather than ``.`` to separate components in a compressed tag)." +#: ../source/specifications/pyproject-toml.rst:315 +msgid "TOML_ type: table with keys and values of strings" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:286 -msgid "Who will maintain the registry of abbreviated implementations?" +#: ../source/specifications/pyproject-toml.rst:316 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:284 +#: ../source/specifications/pyproject-toml.rst:319 msgid "" -"New two-letter abbreviations can be requested on the python-dev mailing " -"list. As a rule of thumb, abbreviations are reserved for the current 4 most " -"prominent implementations." +"A table of URLs where the key is the URL label and the value is the URL " +"itself." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:291 -msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +#: ../source/specifications/pyproject-toml.rst:324 +msgid "Entry points" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:289 +#: ../source/specifications/pyproject-toml.rst:326 msgid "" -"No. The compatibility tag is part of the built distribution's metadata. " -"METADATA / PKG-INFO should be valid for an entire distribution, not a single " -"build of that distribution." +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:297 -msgid "Why didn't you mention my favorite Python implementation?" +#: ../source/specifications/pyproject-toml.rst:328 +msgid ":ref:`Entry points specification `" msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:294 +#: ../source/specifications/pyproject-toml.rst:330 msgid "" -"The abbreviated tags facilitate sharing compiled Python code in a public " -"index. Your Python implementation can use this specification too, but with " -"longer tags. Recall that all \"pure Python\" built distributions just use " -"``py``." +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:303 +#: ../source/specifications/pyproject-toml.rst:336 msgid "" -"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " -"implementation?" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." msgstr "" -#: ../source/specifications/platform-compatibility-tags.rst:300 +#: ../source/specifications/pyproject-toml.rst:340 msgid "" -"Since Python 2 does not have an easy way to get to the SOABI (the concept " -"comes from newer versions of Python 3) the reference implementation at the " -"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " -"analogous to newer versions of Python, but in the meantime \"none\" is a " -"good enough way to say \"don't know\"." -msgstr "" - -#: ../source/specifications/pypirc.rst:6 -msgid "The :file:`.pypirc` file" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." msgstr "" -#: ../source/specifications/pypirc.rst:8 +#: ../source/specifications/pyproject-toml.rst:346 msgid "" -"A :file:`.pypirc` file allows you to define the configuration for :term:" -"`package indexes ` (referred to here as \"repositories\"), so " -"that you don't have to enter the URL, username, or password whenever you " -"upload a package with :ref:`twine` or :ref:`flit`." +"Build back-ends MUST raise an error if the metadata defines a ``[project." +"entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` " +"table, as they would be ambiguous in the face of ``[project.scripts]`` and " +"``[project.gui-scripts]``, respectively." msgstr "" -#: ../source/specifications/pypirc.rst:13 -msgid "The format (originally defined by the :ref:`distutils` package) is:" +#: ../source/specifications/pyproject-toml.rst:356 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" msgstr "" -#: ../source/specifications/pypirc.rst:32 +#: ../source/specifications/pyproject-toml.rst:359 msgid "" -"The ``distutils`` section defines an ``index-servers`` field that lists the " -"name of all sections describing a repository." +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" msgstr "" -#: ../source/specifications/pypirc.rst:35 -msgid "Each section describing a repository defines three fields:" +#: ../source/specifications/pyproject-toml.rst:363 +msgid "The (optional) dependencies of the project." msgstr "" -#: ../source/specifications/pypirc.rst:37 -msgid "``repository``: The URL of the repository." +#: ../source/specifications/pyproject-toml.rst:365 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." msgstr "" -#: ../source/specifications/pypirc.rst:38 -msgid "``username``: The registered username on the repository." +#: ../source/specifications/pyproject-toml.rst:370 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values for :ref:" +"`Provides-Extra `. Each value in the array " +"thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." msgstr "" -#: ../source/specifications/pypirc.rst:39 -msgid "``password``: The password that will used to authenticate the username." +#: ../source/specifications/pyproject-toml.rst:386 +msgid "TOML_ type: array of string" msgstr "" -#: ../source/specifications/pypirc.rst:43 +#: ../source/specifications/pyproject-toml.rst:387 msgid "" -"Be aware that this stores your password in plain text. For better security, " -"consider an alternative like `keyring`_, setting environment variables, or " -"providing the password on the command line." +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" msgstr "" -#: ../source/specifications/pypirc.rst:47 +#: ../source/specifications/pyproject-toml.rst:390 msgid "" -"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " -"or modify it. For example, on Linux or macOS, run:" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." msgstr "" -#: ../source/specifications/pypirc.rst:57 -msgid "Common configurations" +#: ../source/specifications/pyproject-toml.rst:396 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." msgstr "" -#: ../source/specifications/pypirc.rst:61 +#: ../source/specifications/pyproject-toml.rst:398 msgid "" -"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " -"use :file:`.pypirc`, but with different defaults. Please refer to each " -"project's documentation for more details and usage instructions." +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:65 +#: ../source/specifications/pyproject-toml.rst:400 msgid "" -"Twine's default configuration mimics a :file:`.pypirc` with repository " -"sections for PyPI and TestPyPI:" +"If the :ref:`core metadata ` specification lists a field as " +"\"Required\", then the metadata MUST specify the key statically or list it " +"in ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it " +"should not be possible for a required key to not be listed somehow in the " +"``[project]`` table)." msgstr "" -#: ../source/specifications/pypirc.rst:81 +#: ../source/specifications/pyproject-toml.rst:405 msgid "" -"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " -"command line, and environment variables to this default configuration." +"If the :ref:`core metadata ` specification lists a field as " +"\"Optional\", the metadata MAY list it in ``dynamic`` if the expectation is " +"a build back-end will provide the data for the key later." msgstr "" -#: ../source/specifications/pypirc.rst:85 -msgid "Using a PyPI token" +#: ../source/specifications/pyproject-toml.rst:409 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." msgstr "" -#: ../source/specifications/pypirc.rst:87 +#: ../source/specifications/pyproject-toml.rst:411 msgid "" -"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " -"similar to:" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." msgstr "" -#: ../source/specifications/pypirc.rst:96 +#: ../source/specifications/pyproject-toml.rst:415 msgid "" -"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " -"the API token from your TestPyPI account." +"Build back-ends MUST raise an error if the metadata specifies a key in " +"``dynamic`` but the build back-end was unable to determine the data for it " +"(omitting the data, if determined to be the accurate value, is acceptable)." msgstr "" -#: ../source/specifications/pypirc.rst:102 -msgid "Using another package index" +#: ../source/specifications/pyproject-toml.rst:425 +msgid "Arbitrary tool configuration: the ``[tool]`` table" msgstr "" -#: ../source/specifications/pypirc.rst:104 +#: ../source/specifications/pyproject-toml.rst:427 msgid "" -"To configure an additional repository, you'll need to redefine the ``index-" -"servers`` field to include the repository name. Here is a complete example " -"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." msgstr "" -#: ../source/specifications/pypirc.rst:131 +#: ../source/specifications/pyproject-toml.rst:433 msgid "" -"Instead of using the ``password`` field, consider saving your API tokens and " -"passwords securely using `keyring`_ (which is installed by Twine):" +"A mechanism is needed to allocate names within the ``tool.*`` namespace, to " +"make sure that different projects do not attempt to use the same sub-table " +"and collide. Our rule is that a project can use the subtable ``tool.$NAME`` " +"if, and only if, they own the entry for ``$NAME`` in the Cheeseshop/PyPI." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:5 -msgid "Recording installed projects" +#: ../source/specifications/pyproject-toml.rst:444 +msgid "" +"This specification was originally defined in :pep:`518` (``[build-system]`` " +"and ``[tool]`` tables) and :pep:`621` (``[project]`` table)." msgstr "" #: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 msgid "" "This document specifies a common format of recording information about " "Python :term:`projects ` installed in an environment. A common " @@ -15470,7 +15358,7 @@ msgid "" "regardless of how they were installed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:12 +#: ../source/specifications/recording-installed-packages.rst:14 msgid "" "Almost all information is optional. This allows tools outside the Python " "ecosystem, such as Linux package managers, to integrate with Python tooling " @@ -15479,11 +15367,11 @@ msgid "" "still record the name and version of the installed project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:21 +#: ../source/specifications/recording-installed-packages.rst:23 msgid "History and change workflow" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:23 +#: ../source/specifications/recording-installed-packages.rst:25 msgid "" "The metadata described here was first specified in :pep:`376`, and later " "amended in :pep:`627` (and other PEPs). It was formerly known as *Database " @@ -15494,21 +15382,21 @@ msgid "" "made through the PEP process (see :pep:`1`)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:31 +#: ../source/specifications/recording-installed-packages.rst:33 msgid "" "While this document is the normative specification, the PEPs that introduce " "changes to it may include additional information such as rationales and " "backwards compatibility considerations." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:39 +#: ../source/specifications/recording-installed-packages.rst:41 msgid "" "Each project installed from a distribution must, in addition to files, " "install a \"``.dist-info``\" directory located alongside importable modules " "and packages (commonly, the ``site-packages`` directory)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:43 +#: ../source/specifications/recording-installed-packages.rst:45 msgid "" "This directory is named as ``{name}-{version}.dist-info``, with ``name`` and " "``version`` fields corresponding to :ref:`core-metadata`. Both fields must " @@ -15520,7 +15408,7 @@ msgid "" "``version`` fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:51 +#: ../source/specifications/recording-installed-packages.rst:53 msgid "" "Historically, tools have failed to replace dot characters or normalize case " "in the ``name`` field, or not perform normalization in the ``version`` " @@ -15531,7 +15419,7 @@ msgid "" "existing tools are encouraged to start normalizing those fields." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:61 +#: ../source/specifications/recording-installed-packages.rst:63 msgid "" "The ``.dist-info`` directory's name is formatted to unambiguously represent " "a distribution as a filesystem path. Tools presenting a distribution name to " @@ -15543,41 +15431,41 @@ msgid "" "name when displaying distribution information." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:70 +#: ../source/specifications/recording-installed-packages.rst:72 msgid "" "This ``.dist-info`` directory may contain the following files, described in " "detail below:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:73 +#: ../source/specifications/recording-installed-packages.rst:75 msgid "``METADATA``: contains project metadata" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:74 +#: ../source/specifications/recording-installed-packages.rst:76 msgid "``RECORD``: records the list of installed files." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:75 +#: ../source/specifications/recording-installed-packages.rst:77 msgid "" "``INSTALLER``: records the name of the tool used to install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:76 +#: ../source/specifications/recording-installed-packages.rst:78 msgid "``entry_points.txt``: see :ref:`entry-points` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:77 +#: ../source/specifications/recording-installed-packages.rst:79 msgid "``direct_url.json``: see :ref:`direct-url` for details" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:79 +#: ../source/specifications/recording-installed-packages.rst:81 msgid "" "The ``METADATA`` file is mandatory. All other files may be omitted at the " "installing tool's discretion. Additional installer-specific files may be " "present." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:85 +#: ../source/specifications/recording-installed-packages.rst:87 msgid "" "The :ref:`binary-distribution-format` specification describes additional " "files that may appear in the ``.dist-info`` directory of a :term:`Wheel`. " @@ -15585,7 +15473,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:90 +#: ../source/specifications/recording-installed-packages.rst:92 msgid "" "The previous versions of this specification also specified a ``REQUESTED`` " "file. This file is now considered a tool-specific extension, but may be " @@ -15593,58 +15481,58 @@ msgid "" "peps/pep-0376/#requested>`_ for its original meaning." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:97 +#: ../source/specifications/recording-installed-packages.rst:99 msgid "The METADATA file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:99 +#: ../source/specifications/recording-installed-packages.rst:101 msgid "" "The ``METADATA`` file contains metadata as described in the :ref:`core-" "metadata` specification, version 1.1 or greater." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:102 +#: ../source/specifications/recording-installed-packages.rst:104 msgid "" "The ``METADATA`` file is mandatory. If it cannot be created, or if required " "core metadata is not available, installers must report an error and fail to " "install the project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:108 +#: ../source/specifications/recording-installed-packages.rst:110 msgid "The RECORD file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:110 +#: ../source/specifications/recording-installed-packages.rst:112 msgid "" "The ``RECORD`` file holds the list of installed files. It is a CSV file " "containing one record (line) per installed file." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:113 +#: ../source/specifications/recording-installed-packages.rst:115 msgid "" "The CSV dialect must be readable with the default ``reader`` of Python's " "``csv`` module:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:116 +#: ../source/specifications/recording-installed-packages.rst:118 msgid "field delimiter: ``,`` (comma)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:117 +#: ../source/specifications/recording-installed-packages.rst:119 msgid "quoting char: ``\"`` (straight double quote)," msgstr "" -#: ../source/specifications/recording-installed-packages.rst:118 +#: ../source/specifications/recording-installed-packages.rst:120 msgid "line terminator: either ``\\r\\n`` or ``\\n``." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:120 +#: ../source/specifications/recording-installed-packages.rst:122 msgid "" "Each record is composed of three elements: the file's **path**, the **hash** " "of the contents, and its **size**." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:123 +#: ../source/specifications/recording-installed-packages.rst:125 msgid "" "The *path* may be either absolute, or relative to the directory containing " "the ``.dist-info`` directory (commonly, the ``site-packages`` directory). On " @@ -15652,7 +15540,7 @@ msgid "" "`` or ``\\``)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:128 +#: ../source/specifications/recording-installed-packages.rst:130 msgid "" "The *hash* is either an empty string or the name of a hash algorithm from " "``hashlib.algorithms_guaranteed``, followed by the equals character ``=`` " @@ -15660,13 +15548,13 @@ msgid "" "encoding (``base64.urlsafe_b64encode(digest)`` with trailing ``=`` removed)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:133 +#: ../source/specifications/recording-installed-packages.rst:135 msgid "" "The *size* is either the empty string, or file's size in bytes, as a base 10 " "integer." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:136 +#: ../source/specifications/recording-installed-packages.rst:138 msgid "" "For any file, either or both of the *hash* and *size* fields may be left " "empty. Commonly, entries for ``.pyc`` files and the ``RECORD`` file itself " @@ -15675,7 +15563,7 @@ msgid "" "project." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:142 +#: ../source/specifications/recording-installed-packages.rst:144 msgid "" "If the ``RECORD`` file is present, it must list all installed files of the " "project, except ``.pyc`` files corresponding to ``.py`` files listed in " @@ -15684,18 +15572,18 @@ msgid "" "should not be listed." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:149 +#: ../source/specifications/recording-installed-packages.rst:151 msgid "" "To completely uninstall a package, a tool needs to remove all files listed " "in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " "to removed ``.py`` files, and any directories emptied by the uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:154 +#: ../source/specifications/recording-installed-packages.rst:156 msgid "Here is an example snippet of a possible ``RECORD`` file::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:173 +#: ../source/specifications/recording-installed-packages.rst:175 msgid "" "If the ``RECORD`` file is missing, tools that rely on ``.dist-info`` must " "not attempt to uninstall or upgrade the package. (This restriction does not " @@ -15703,7 +15591,7 @@ msgid "" "package managers in Linux distros.)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:180 +#: ../source/specifications/recording-installed-packages.rst:182 msgid "" "It is *strongly discouraged* for an installed package to modify itself (e." "g., store cache files under its namespace in ``site-packages``). Changes " @@ -15713,11 +15601,11 @@ msgid "" "unlisted files in place (possibly resulting in a zombie namespace package)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:189 +#: ../source/specifications/recording-installed-packages.rst:191 msgid "The INSTALLER file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:191 +#: ../source/specifications/recording-installed-packages.rst:193 msgid "" "If present, ``INSTALLER`` is a single-line text file naming the tool used to " "install the project. If the installer is executable from the command line, " @@ -15725,15 +15613,15 @@ msgid "" "a printable ASCII string." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:197 +#: ../source/specifications/recording-installed-packages.rst:199 msgid "The file can be terminated by zero or more ASCII whitespace characters." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:199 +#: ../source/specifications/recording-installed-packages.rst:201 msgid "Here are examples of two possible ``INSTALLER`` files::" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:207 +#: ../source/specifications/recording-installed-packages.rst:209 msgid "" "This value should be used for informational purposes only. For example, if a " "tool is asked to uninstall a project but finds no ``RECORD`` file, it may " @@ -15741,11 +15629,11 @@ msgid "" "uninstallation." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:214 +#: ../source/specifications/recording-installed-packages.rst:216 msgid "The entry_points.txt file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:216 +#: ../source/specifications/recording-installed-packages.rst:218 msgid "" "This file MAY be created by installers to indicate when packages contain " "components intended for discovery and use by other code, including console " @@ -15753,29 +15641,29 @@ msgid "" "execution." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:221 +#: ../source/specifications/recording-installed-packages.rst:223 msgid "Its detailed specification is at :ref:`entry-points`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:225 +#: ../source/specifications/recording-installed-packages.rst:227 msgid "The direct_url.json file" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:227 +#: ../source/specifications/recording-installed-packages.rst:229 msgid "" "This file MUST be created by installers when installing a distribution from " "a requirement specifying a direct URL reference (including a VCS URL)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:233 +#: ../source/specifications/recording-installed-packages.rst:235 msgid "Its detailed specification is at :ref:`direct-url`." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:237 +#: ../source/specifications/recording-installed-packages.rst:239 msgid "Intentionally preventing changes to installed packages" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:239 +#: ../source/specifications/recording-installed-packages.rst:241 msgid "" "In some cases (such as when needing to manage external dependencies in " "addition to Python ecosystem dependencies), it is desirable for a tool that " @@ -15784,11 +15672,11 @@ msgid "" "so may cause compatibility problems with the wider environment." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:245 +#: ../source/specifications/recording-installed-packages.rst:247 msgid "To achieve this, affected tools should take the following steps:" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:247 +#: ../source/specifications/recording-installed-packages.rst:249 msgid "" "Rename or remove the ``RECORD`` file to prevent changes via other tools (e." "g. appending a suffix to create a non-standard ``RECORD.tool`` file if the " @@ -15796,14 +15684,14 @@ msgid "" "package contents are tracked and managed via other means)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:251 +#: ../source/specifications/recording-installed-packages.rst:253 msgid "" "Write an ``INSTALLER`` file indicating the name of the tool that should be " "used to manage the package (this allows ``RECORD``-aware tools to provide " "better error notices when asked to modify affected packages)" msgstr "" -#: ../source/specifications/recording-installed-packages.rst:255 +#: ../source/specifications/recording-installed-packages.rst:257 msgid "" "Python runtime providers may also prevent inadvertent modification of " "platform provided packages by modifying the default Python package " @@ -15812,7 +15700,7 @@ msgid "" "Python import path)." msgstr "" -#: ../source/specifications/recording-installed-packages.rst:260 +#: ../source/specifications/recording-installed-packages.rst:262 msgid "" "In some circumstances, it may be desirable to block even installation of " "additional packages via Python-specific tools. For these cases refer to :ref:" @@ -15946,10 +15834,10 @@ msgid "" "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " "source files of the package. The name and version MUST match the metadata " "stored in the file. This directory must also contain a :file:`pyproject." -"toml` in the format defined in :ref:`declaring-build-dependencies`, and a " -"``PKG-INFO`` file containing metadata in the format described in the :ref:" -"`core-metadata` specification. The metadata MUST conform to at least version " -"2.2 of the metadata specification." +"toml` in the format defined in :ref:`pyproject-toml-spec`, and a ``PKG-" +"INFO`` file containing metadata in the format described in the :ref:`core-" +"metadata` specification. The metadata MUST conform to at least version 2.2 " +"of the metadata specification." msgstr "" #: ../source/specifications/source-distribution-format.rst:65 @@ -16119,24 +16007,24 @@ msgstr "" msgid "December 2000: Source distributions standardized in :pep:`643`" msgstr "" -#: ../source/specifications/version-specifiers.rst:5 -#: ../source/specifications/version-specifiers.rst:776 +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:778 msgid "Version specifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:8 +#: ../source/specifications/version-specifiers.rst:10 msgid "" "This specification describes a scheme for identifying versions of Python " "software distributions, and declaring dependencies on particular versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:13 +#: ../source/specifications/version-specifiers.rst:15 #, fuzzy #| msgid "Specifications" msgid "Definitions" msgstr "規格" -#: ../source/specifications/version-specifiers.rst:15 +#: ../source/specifications/version-specifiers.rst:17 msgid "" "The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " "NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and " @@ -16144,7 +16032,7 @@ msgid "" "`2119`." msgstr "" -#: ../source/specifications/version-specifiers.rst:19 +#: ../source/specifications/version-specifiers.rst:21 msgid "" "\"Build tools\" are automated tools intended to run on development systems, " "producing source and binary distribution archives. Build tools may also be " @@ -16152,19 +16040,19 @@ msgid "" "sdists rather than prebuilt binary archives." msgstr "" -#: ../source/specifications/version-specifiers.rst:24 +#: ../source/specifications/version-specifiers.rst:26 msgid "" "\"Index servers\" are active distribution registries which publish version " "and dependency metadata and place constraints on the permitted metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:27 +#: ../source/specifications/version-specifiers.rst:29 msgid "" "\"Publication tools\" are automated tools intended to run on development " "systems and upload source and binary distribution archives to index servers." msgstr "" -#: ../source/specifications/version-specifiers.rst:30 +#: ../source/specifications/version-specifiers.rst:32 msgid "" "\"Installation tools\" are integration tools specifically intended to run on " "deployment targets, consuming source and binary distribution archives from " @@ -16172,25 +16060,25 @@ msgid "" "target system." msgstr "" -#: ../source/specifications/version-specifiers.rst:35 +#: ../source/specifications/version-specifiers.rst:37 msgid "" "\"Automated tools\" is a collective term covering build tools, index " "servers, publication tools, integration tools and any other software that " "produces or consumes distribution version and dependency metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:41 +#: ../source/specifications/version-specifiers.rst:43 #, fuzzy msgid "Version scheme" msgstr "翻譯" -#: ../source/specifications/version-specifiers.rst:43 +#: ../source/specifications/version-specifiers.rst:45 msgid "" "Distributions are identified by a public version identifier which supports " "all defined version comparison operations" msgstr "" -#: ../source/specifications/version-specifiers.rst:46 +#: ../source/specifications/version-specifiers.rst:48 msgid "" "The version scheme is used both to describe the distribution version " "provided by a particular distribution archive, as well as to place " @@ -16198,26 +16086,26 @@ msgid "" "the software." msgstr "" -#: ../source/specifications/version-specifiers.rst:55 +#: ../source/specifications/version-specifiers.rst:57 msgid "Public version identifiers" msgstr "" -#: ../source/specifications/version-specifiers.rst:57 +#: ../source/specifications/version-specifiers.rst:59 msgid "" "The canonical public version identifiers MUST comply with the following " "scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:62 +#: ../source/specifications/version-specifiers.rst:64 msgid "" "Public version identifiers MUST NOT include leading or trailing whitespace." msgstr "" -#: ../source/specifications/version-specifiers.rst:64 +#: ../source/specifications/version-specifiers.rst:66 msgid "Public version identifiers MUST be unique within a given distribution." msgstr "" -#: ../source/specifications/version-specifiers.rst:66 +#: ../source/specifications/version-specifiers.rst:68 msgid "" "Installation tools SHOULD ignore any public versions which do not comply " "with this scheme but MUST also include the normalizations specified below. " @@ -16225,7 +16113,7 @@ msgid "" "versions are detected." msgstr "" -#: ../source/specifications/version-specifiers.rst:71 +#: ../source/specifications/version-specifiers.rst:73 msgid "" "See also :ref:`version-specifiers-regex` which provides a regular expression " "to check strict conformance with the canonical format, as well as a more " @@ -16233,63 +16121,63 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:76 +#: ../source/specifications/version-specifiers.rst:78 msgid "Public version identifiers are separated into up to five segments:" msgstr "" -#: ../source/specifications/version-specifiers.rst:78 +#: ../source/specifications/version-specifiers.rst:80 msgid "Epoch segment: ``N!``" msgstr "" -#: ../source/specifications/version-specifiers.rst:79 +#: ../source/specifications/version-specifiers.rst:81 msgid "Release segment: ``N(.N)*``" msgstr "" -#: ../source/specifications/version-specifiers.rst:80 +#: ../source/specifications/version-specifiers.rst:82 msgid "Pre-release segment: ``{a|b|rc}N``" msgstr "" -#: ../source/specifications/version-specifiers.rst:81 +#: ../source/specifications/version-specifiers.rst:83 msgid "Post-release segment: ``.postN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:82 +#: ../source/specifications/version-specifiers.rst:84 msgid "Development release segment: ``.devN``" msgstr "" -#: ../source/specifications/version-specifiers.rst:84 +#: ../source/specifications/version-specifiers.rst:86 msgid "" "Any given release will be a \"final release\", \"pre-release\", \"post-" "release\" or \"developmental release\" as defined in the following sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:87 +#: ../source/specifications/version-specifiers.rst:89 msgid "" "All numeric components MUST be non-negative integers represented as " "sequences of ASCII digits." msgstr "" -#: ../source/specifications/version-specifiers.rst:90 +#: ../source/specifications/version-specifiers.rst:92 msgid "" "All numeric components MUST be interpreted and ordered according to their " "numeric value, not as text strings." msgstr "" -#: ../source/specifications/version-specifiers.rst:93 +#: ../source/specifications/version-specifiers.rst:95 msgid "" "All numeric components MAY be zero. Except as described below for the " "release segment, a numeric component of zero has no special significance " "aside from always being the lowest possible value in the version ordering." msgstr "" -#: ../source/specifications/version-specifiers.rst:99 +#: ../source/specifications/version-specifiers.rst:101 msgid "" "Some hard to read version identifiers are permitted by this scheme in order " "to better accommodate the wide range of versioning practices across existing " "public and private Python projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:103 +#: ../source/specifications/version-specifiers.rst:105 msgid "" "Accordingly, some of the versioning practices which are technically " "permitted by the specification are strongly discouraged for new projects. " @@ -16297,11 +16185,11 @@ msgid "" "sections." msgstr "" -#: ../source/specifications/version-specifiers.rst:112 +#: ../source/specifications/version-specifiers.rst:114 msgid "Local version identifiers MUST comply with the following scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:116 +#: ../source/specifications/version-specifiers.rst:118 msgid "" "They consist of a normal public version identifier (as defined in the " "previous section), along with an arbitrary \"local version label\", " @@ -16310,7 +16198,7 @@ msgid "" "imposed." msgstr "" -#: ../source/specifications/version-specifiers.rst:121 +#: ../source/specifications/version-specifiers.rst:123 msgid "" "Local version identifiers are used to denote fully API (and, if applicable, " "ABI) compatible patched versions of upstream projects. For example, these " @@ -16320,7 +16208,7 @@ msgid "" "Linux distribution)." msgstr "" -#: ../source/specifications/version-specifiers.rst:128 +#: ../source/specifications/version-specifiers.rst:130 msgid "" "The inclusion of the local version label makes it possible to differentiate " "upstream releases from potentially altered rebuilds by downstream " @@ -16329,7 +16217,7 @@ msgid "" "it may not contain the exact same code as the corresponding upstream release." msgstr "" -#: ../source/specifications/version-specifiers.rst:134 +#: ../source/specifications/version-specifiers.rst:136 msgid "" "To ensure local version identifiers can be readily incorporated as part of " "filenames and URLs, and to avoid formatting inconsistencies in hexadecimal " @@ -16337,23 +16225,23 @@ msgid "" "set of permitted characters:" msgstr "" -#: ../source/specifications/version-specifiers.rst:139 +#: ../source/specifications/version-specifiers.rst:141 msgid "ASCII letters (``[a-zA-Z]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:140 +#: ../source/specifications/version-specifiers.rst:142 msgid "ASCII digits (``[0-9]``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:141 +#: ../source/specifications/version-specifiers.rst:143 msgid "periods (``.``)" msgstr "" -#: ../source/specifications/version-specifiers.rst:143 +#: ../source/specifications/version-specifiers.rst:145 msgid "Local version labels MUST start and end with an ASCII letter or digit." msgstr "" -#: ../source/specifications/version-specifiers.rst:145 +#: ../source/specifications/version-specifiers.rst:147 msgid "" "Comparison and ordering of local versions considers each segment of the " "local version (divided by a ``.``) separately. If a segment consists " @@ -16367,7 +16255,7 @@ msgid "" "segments match the beginning of the longer local version's segments exactly." msgstr "" -#: ../source/specifications/version-specifiers.rst:156 +#: ../source/specifications/version-specifiers.rst:158 msgid "" "An \"upstream project\" is a project that defines its own public versions. A " "\"downstream project\" is one which tracks and redistributes an upstream " @@ -16375,7 +16263,7 @@ msgid "" "of the upstream project." msgstr "" -#: ../source/specifications/version-specifiers.rst:161 +#: ../source/specifications/version-specifiers.rst:163 msgid "" "Local version identifiers SHOULD NOT be used when publishing upstream " "projects to a public index server, but MAY be used to identify private " @@ -16387,36 +16275,36 @@ msgid "" "upstream projects, it MUST NOT allow the use of local version identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:171 +#: ../source/specifications/version-specifiers.rst:173 msgid "" "Source distributions using a local version identifier SHOULD provide the " "``python.integrator`` extension metadata (as defined in :pep:`459`)." msgstr "" -#: ../source/specifications/version-specifiers.rst:176 +#: ../source/specifications/version-specifiers.rst:178 msgid "Final releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:178 +#: ../source/specifications/version-specifiers.rst:180 msgid "" "A version identifier that consists solely of a release segment and " "optionally an epoch identifier is termed a \"final release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:181 +#: ../source/specifications/version-specifiers.rst:183 msgid "" "The release segment consists of one or more non-negative integer values, " "separated by dots::" msgstr "" -#: ../source/specifications/version-specifiers.rst:186 +#: ../source/specifications/version-specifiers.rst:188 msgid "" "Final releases within a project MUST be numbered in a consistently " "increasing fashion, otherwise automated tools will not be able to upgrade " "them correctly." msgstr "" -#: ../source/specifications/version-specifiers.rst:190 +#: ../source/specifications/version-specifiers.rst:192 msgid "" "Comparison and ordering of release segments considers the numeric value of " "each component of the release segment in turn. When comparing release " @@ -16424,21 +16312,25 @@ msgid "" "out with additional zeros as necessary." msgstr "" -#: ../source/specifications/version-specifiers.rst:195 +#: ../source/specifications/version-specifiers.rst:197 msgid "" "While any number of additional components after the first are permitted " "under this scheme, the most common variants are to use two components " "(\"major.minor\") or three components (\"major.minor.micro\")." msgstr "" -#: ../source/specifications/version-specifiers.rst:214 +#: ../source/specifications/version-specifiers.rst:201 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:216 msgid "" "A release series is any set of final release numbers that start with a " "common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " "part of the ``3.3`` release series." msgstr "" -#: ../source/specifications/version-specifiers.rst:220 +#: ../source/specifications/version-specifiers.rst:222 msgid "" "``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as the " "release segment comparison rules implicit expand the two component form to " @@ -16446,35 +16338,35 @@ msgid "" "components." msgstr "" -#: ../source/specifications/version-specifiers.rst:225 +#: ../source/specifications/version-specifiers.rst:227 msgid "" "Date based release segments are also permitted. An example of a date based " "release scheme using the year and month of the release::" msgstr "" -#: ../source/specifications/version-specifiers.rst:237 +#: ../source/specifications/version-specifiers.rst:239 msgid "Pre-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:239 +#: ../source/specifications/version-specifiers.rst:241 msgid "" "Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " "support testing by their users prior to a final release." msgstr "" -#: ../source/specifications/version-specifiers.rst:242 +#: ../source/specifications/version-specifiers.rst:244 msgid "" "If used as part of a project's development cycle, these pre-releases are " "indicated by including a pre-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:250 +#: ../source/specifications/version-specifiers.rst:252 msgid "" "A version identifier that consists solely of a release segment and a pre-" "release segment is termed a \"pre-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:253 +#: ../source/specifications/version-specifiers.rst:255 msgid "" "The pre-release segment consists of an alphabetical identifier for the pre-" "release phase, along with a non-negative integer value. Pre-releases for a " @@ -16482,48 +16374,48 @@ msgid "" "and then by the numerical component within that phase." msgstr "" -#: ../source/specifications/version-specifiers.rst:258 +#: ../source/specifications/version-specifiers.rst:260 msgid "" "Installation tools MAY accept both ``c`` and ``rc`` releases for a common " "release segment in order to handle some existing legacy distributions." msgstr "" -#: ../source/specifications/version-specifiers.rst:261 +#: ../source/specifications/version-specifiers.rst:263 msgid "" "Installation tools SHOULD interpret ``c`` versions as being equivalent to " "``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:264 +#: ../source/specifications/version-specifiers.rst:266 msgid "" "Build tools, publication tools and index servers SHOULD disallow the " "creation of both ``rc`` and ``c`` releases for a common release segment." msgstr "" -#: ../source/specifications/version-specifiers.rst:269 +#: ../source/specifications/version-specifiers.rst:271 msgid "Post-releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:271 +#: ../source/specifications/version-specifiers.rst:273 msgid "" "Some projects use post-releases to address minor errors in a final release " "that do not affect the distributed software (for example, correcting an " "error in the release notes)." msgstr "" -#: ../source/specifications/version-specifiers.rst:275 +#: ../source/specifications/version-specifiers.rst:277 msgid "" "If used as part of a project's development cycle, these post-releases are " "indicated by including a post-release segment in the version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:280 +#: ../source/specifications/version-specifiers.rst:282 msgid "" "A version identifier that includes a post-release segment without a " "developmental release segment is termed a \"post-release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:283 +#: ../source/specifications/version-specifiers.rst:285 msgid "" "The post-release segment consists of the string ``.post``, followed by a non-" "negative integer value. Post-releases are ordered by their numerical " @@ -16531,7 +16423,7 @@ msgid "" "subsequent release." msgstr "" -#: ../source/specifications/version-specifiers.rst:290 +#: ../source/specifications/version-specifiers.rst:292 msgid "" "The use of post-releases to publish maintenance releases containing actual " "bug fixes is strongly discouraged. In general, it is better to use a longer " @@ -16539,11 +16431,11 @@ msgid "" "release." msgstr "" -#: ../source/specifications/version-specifiers.rst:295 +#: ../source/specifications/version-specifiers.rst:297 msgid "Post-releases are also permitted for pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:303 +#: ../source/specifications/version-specifiers.rst:305 msgid "" "Creating post-releases of pre-releases is strongly discouraged, as it makes " "the version identifier difficult to parse for human readers. In general, it " @@ -16551,11 +16443,11 @@ msgid "" "the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:310 +#: ../source/specifications/version-specifiers.rst:312 msgid "Developmental releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:312 +#: ../source/specifications/version-specifiers.rst:314 msgid "" "Some projects make regular developmental releases, and system packagers " "(especially for Linux distributions) may wish to create early releases " @@ -16563,20 +16455,20 @@ msgid "" "releases." msgstr "" -#: ../source/specifications/version-specifiers.rst:317 +#: ../source/specifications/version-specifiers.rst:319 msgid "" "If used as part of a project's development cycle, these developmental " "releases are indicated by including a developmental release segment in the " "version identifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:323 +#: ../source/specifications/version-specifiers.rst:325 msgid "" "A version identifier that includes a developmental release segment is termed " "a \"developmental release\"." msgstr "" -#: ../source/specifications/version-specifiers.rst:326 +#: ../source/specifications/version-specifiers.rst:328 msgid "" "The developmental release segment consists of the string ``.dev``, followed " "by a non-negative integer value. Developmental releases are ordered by their " @@ -16585,13 +16477,13 @@ msgid "" "previous release (including any post-releases)." msgstr "" -#: ../source/specifications/version-specifiers.rst:332 +#: ../source/specifications/version-specifiers.rst:334 msgid "" "Developmental releases are also permitted for pre-releases and post-" "releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:342 +#: ../source/specifications/version-specifiers.rst:344 msgid "" "While they may be useful for continuous integration purposes, publishing " "developmental releases of pre-releases to general purpose public index " @@ -16601,29 +16493,29 @@ msgid "" "by incrementing the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:349 +#: ../source/specifications/version-specifiers.rst:351 msgid "" "Developmental releases of post-releases are also strongly discouraged, but " "they may be appropriate for projects which use the post-release notation for " "full maintenance releases which may include code changes." msgstr "" -#: ../source/specifications/version-specifiers.rst:355 +#: ../source/specifications/version-specifiers.rst:357 #, fuzzy msgid "Version epochs" msgstr "翻譯" -#: ../source/specifications/version-specifiers.rst:357 +#: ../source/specifications/version-specifiers.rst:359 msgid "" "If included in a version identifier, the epoch appears before all other " "components, separated from the release segment by an exclamation mark::" msgstr "" -#: ../source/specifications/version-specifiers.rst:362 +#: ../source/specifications/version-specifiers.rst:364 msgid "If no explicit epoch is given, the implicit epoch is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:364 +#: ../source/specifications/version-specifiers.rst:366 msgid "" "Most version identifiers will not include an epoch, as an explicit epoch is " "only needed if a project *changes* the way it handles version numbering in a " @@ -16634,14 +16526,14 @@ msgid "" "using the normal sorting scheme::" msgstr "" -#: ../source/specifications/version-specifiers.rst:378 +#: ../source/specifications/version-specifiers.rst:380 msgid "" "However, by specifying an explicit epoch, the sort order can be changed " "appropriately, as all versions from a later epoch are sorted after versions " "from an earlier epoch::" msgstr "" -#: ../source/specifications/version-specifiers.rst:394 +#: ../source/specifications/version-specifiers.rst:396 msgid "" "In order to maintain better compatibility with existing versions there are a " "number of \"alternative\" syntaxes that MUST be taken into account when " @@ -16649,23 +16541,23 @@ msgid "" "however they should be \"normalized\" to the standard syntax defined above." msgstr "" -#: ../source/specifications/version-specifiers.rst:401 +#: ../source/specifications/version-specifiers.rst:403 msgid "Case sensitivity" msgstr "" -#: ../source/specifications/version-specifiers.rst:403 +#: ../source/specifications/version-specifiers.rst:405 msgid "" "All ascii letters should be interpreted case insensitively within a version " "and the normal form is lowercase. This allows versions such as ``1.1RC1`` " "which would be normalized to ``1.1rc1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:409 +#: ../source/specifications/version-specifiers.rst:411 #, fuzzy msgid "Integer Normalization" msgstr "翻譯" -#: ../source/specifications/version-specifiers.rst:411 +#: ../source/specifications/version-specifiers.rst:413 msgid "" "All integers are interpreted via the ``int()`` built in and normalize to the " "string form of the output. This means that an integer version of ``00`` " @@ -16674,11 +16566,11 @@ msgid "" "version such as ``1.0+foo0100`` which is already in its normalized form." msgstr "" -#: ../source/specifications/version-specifiers.rst:419 +#: ../source/specifications/version-specifiers.rst:421 msgid "Pre-release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:421 +#: ../source/specifications/version-specifiers.rst:423 msgid "" "Pre-releases should allow a ``.``, ``-``, or ``_`` separator between the " "release segment and the pre-release segment. The normal form for this is " @@ -16688,11 +16580,11 @@ msgid "" "versions such as ``1.0a.1`` which would be normalized to ``1.0a1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:430 +#: ../source/specifications/version-specifiers.rst:432 msgid "Pre-release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:432 +#: ../source/specifications/version-specifiers.rst:434 msgid "" "Pre-releases allow the additional spellings of ``alpha``, ``beta``, ``c``, " "``pre``, and ``preview`` for ``a``, ``b``, ``rc``, ``rc``, and ``rc`` " @@ -16702,11 +16594,11 @@ msgid "" "forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:441 +#: ../source/specifications/version-specifiers.rst:443 msgid "Implicit pre-release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:443 +#: ../source/specifications/version-specifiers.rst:445 msgid "" "Pre releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16714,11 +16606,11 @@ msgid "" "``1.2a0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:449 +#: ../source/specifications/version-specifiers.rst:451 msgid "Post release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:451 +#: ../source/specifications/version-specifiers.rst:453 msgid "" "Post releases allow a ``.``, ``-``, or ``_`` separator as well as omitting " "the separator all together. The normal form of this is with the ``.`` " @@ -16729,11 +16621,11 @@ msgid "" "post2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:460 +#: ../source/specifications/version-specifiers.rst:462 msgid "Post release spelling" msgstr "" -#: ../source/specifications/version-specifiers.rst:462 +#: ../source/specifications/version-specifiers.rst:464 msgid "" "Post-releases allow the additional spellings of ``rev`` and ``r``. This " "allows versions such as ``1.0-r4`` which normalizes to ``1.0.post4``. As " @@ -16741,11 +16633,11 @@ msgid "" "equivalent to their normal forms." msgstr "" -#: ../source/specifications/version-specifiers.rst:469 +#: ../source/specifications/version-specifiers.rst:471 msgid "Implicit post release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:471 +#: ../source/specifications/version-specifiers.rst:473 msgid "" "Post releases allow omitting the numeral in which case it is implicitly " "assumed to be ``0``. The normal form for this is to include the ``0`` " @@ -16753,11 +16645,11 @@ msgid "" "``1.2.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:477 +#: ../source/specifications/version-specifiers.rst:479 msgid "Implicit post releases" msgstr "" -#: ../source/specifications/version-specifiers.rst:479 +#: ../source/specifications/version-specifiers.rst:481 msgid "" "Post releases allow omitting the ``post`` signifier all together. When using " "this form the separator MUST be ``-`` and no other form is allowed. This " @@ -16767,11 +16659,11 @@ msgid "" "and it does *not* normalize to ``1.0.post0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:488 +#: ../source/specifications/version-specifiers.rst:490 msgid "Development release separators" msgstr "" -#: ../source/specifications/version-specifiers.rst:490 +#: ../source/specifications/version-specifiers.rst:492 msgid "" "Development releases allow a ``.``, ``-``, or a ``_`` separator as well as " "omitting the separator all together. The normal form of this is with the ``." @@ -16779,11 +16671,11 @@ msgid "" "normalize to ``1.2.dev2``." msgstr "" -#: ../source/specifications/version-specifiers.rst:497 +#: ../source/specifications/version-specifiers.rst:499 msgid "Implicit development release number" msgstr "" -#: ../source/specifications/version-specifiers.rst:499 +#: ../source/specifications/version-specifiers.rst:501 msgid "" "Development releases allow omitting the numeral in which case it is " "implicitly assumed to be ``0``. The normal form for this is to include the " @@ -16791,11 +16683,11 @@ msgid "" "normalized to ``1.2.dev0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:506 +#: ../source/specifications/version-specifiers.rst:508 msgid "Local version segments" msgstr "" -#: ../source/specifications/version-specifiers.rst:508 +#: ../source/specifications/version-specifiers.rst:510 msgid "" "With a local version, in addition to the use of ``.`` as a separator of " "segments, the use of ``-`` and ``_`` is also acceptable. The normal form is " @@ -16803,11 +16695,11 @@ msgid "" "be normalized to ``1.0+ubuntu.1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:515 +#: ../source/specifications/version-specifiers.rst:517 msgid "Preceding v character" msgstr "" -#: ../source/specifications/version-specifiers.rst:517 +#: ../source/specifications/version-specifiers.rst:519 msgid "" "In order to support the common version notation of ``v1.0`` versions may be " "preceded by a single literal ``v`` character. This character MUST be ignored " @@ -16816,11 +16708,11 @@ msgid "" "equivalent." msgstr "" -#: ../source/specifications/version-specifiers.rst:524 +#: ../source/specifications/version-specifiers.rst:526 msgid "Leading and Trailing Whitespace" msgstr "" -#: ../source/specifications/version-specifiers.rst:526 +#: ../source/specifications/version-specifiers.rst:528 msgid "" "Leading and trailing whitespace must be silently ignored and removed from " "all normalized forms of a version. This includes ``\" \"``, ``\\t``, " @@ -16829,11 +16721,11 @@ msgid "" "``1.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:533 +#: ../source/specifications/version-specifiers.rst:535 msgid "Examples of compliant version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:535 +#: ../source/specifications/version-specifiers.rst:537 msgid "" "The standard version scheme is designed to encompass a wide range of " "identification practices across public and private Python projects. In " @@ -16843,7 +16735,7 @@ msgid "" "ensure all compliant tools will order them consistently." msgstr "" -#: ../source/specifications/version-specifiers.rst:542 +#: ../source/specifications/version-specifiers.rst:544 msgid "" "The following examples illustrate a small selection of the different " "approaches projects may choose to identify their releases, while still " @@ -16851,69 +16743,69 @@ msgid "" "be easily determined, both by human users and automated tools." msgstr "" -#: ../source/specifications/version-specifiers.rst:547 +#: ../source/specifications/version-specifiers.rst:549 msgid "Simple \"major.minor\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:556 +#: ../source/specifications/version-specifiers.rst:558 msgid "Simple \"major.minor.micro\" versioning::" msgstr "" -#: ../source/specifications/version-specifiers.rst:564 +#: ../source/specifications/version-specifiers.rst:566 msgid "" "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" msgstr "" -#: ../source/specifications/version-specifiers.rst:576 +#: ../source/specifications/version-specifiers.rst:578 msgid "" "\"major.minor\" versioning with developmental releases, release candidates " "and post-releases for minor corrections::" msgstr "" -#: ../source/specifications/version-specifiers.rst:591 +#: ../source/specifications/version-specifiers.rst:593 msgid "" "Date based releases, using an incrementing serial within each year, skipping " "zero::" msgstr "" -#: ../source/specifications/version-specifiers.rst:605 +#: ../source/specifications/version-specifiers.rst:607 msgid "Summary of permitted suffixes and relative ordering" msgstr "" -#: ../source/specifications/version-specifiers.rst:609 +#: ../source/specifications/version-specifiers.rst:611 msgid "" "This section is intended primarily for authors of tools that automatically " "process distribution metadata, rather than developers of Python " "distributions deciding on a versioning scheme." msgstr "" -#: ../source/specifications/version-specifiers.rst:613 +#: ../source/specifications/version-specifiers.rst:615 msgid "" "The epoch segment of version identifiers MUST be sorted according to the " "numeric value of the given epoch. If no epoch segment is present, the " "implicit numeric value is ``0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:617 +#: ../source/specifications/version-specifiers.rst:619 msgid "" "The release segment of version identifiers MUST be sorted in the same order " "as Python's tuple sorting when the normalized release segment is parsed as " "follows::" msgstr "" -#: ../source/specifications/version-specifiers.rst:623 +#: ../source/specifications/version-specifiers.rst:625 msgid "" "All release segments involved in the comparison MUST be converted to a " "consistent length by padding shorter segments with zeros as needed." msgstr "" -#: ../source/specifications/version-specifiers.rst:626 +#: ../source/specifications/version-specifiers.rst:628 msgid "" "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " "permitted and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:631 +#: ../source/specifications/version-specifiers.rst:633 msgid "" "Note that ``c`` is considered to be semantically equivalent to ``rc`` and " "must be sorted as if it were ``rc``. Tools MAY reject the case of having the " @@ -16921,48 +16813,48 @@ msgid "" "ambiguous and remain in compliance with the specification." msgstr "" -#: ../source/specifications/version-specifiers.rst:636 +#: ../source/specifications/version-specifiers.rst:638 msgid "" "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " "(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " "ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:642 +#: ../source/specifications/version-specifiers.rst:644 msgid "" "Within a post-release (``1.0.post1``), the following suffixes are permitted " "and MUST be ordered as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:647 +#: ../source/specifications/version-specifiers.rst:649 msgid "" "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " "used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0." "post1``)." msgstr "" -#: ../source/specifications/version-specifiers.rst:651 +#: ../source/specifications/version-specifiers.rst:653 msgid "" "Within a pre-release, post-release or development release segment with a " "shared prefix, ordering MUST be by the value of the numeric component." msgstr "" -#: ../source/specifications/version-specifiers.rst:654 +#: ../source/specifications/version-specifiers.rst:656 msgid "The following example covers many of the possible combinations::" msgstr "" -#: ../source/specifications/version-specifiers.rst:679 +#: ../source/specifications/version-specifiers.rst:681 msgid "Version ordering across different metadata versions" msgstr "" -#: ../source/specifications/version-specifiers.rst:681 +#: ../source/specifications/version-specifiers.rst:683 msgid "" "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " "standard version identification or ordering scheme. However metadata v1.2 (:" "pep:`345`) does specify a scheme which is defined in :pep:`386`." msgstr "" -#: ../source/specifications/version-specifiers.rst:685 +#: ../source/specifications/version-specifiers.rst:687 msgid "" "Due to the nature of the simple installer API it is not possible for an " "installer to be aware of which metadata version a particular distribution " @@ -16973,7 +16865,7 @@ msgid "" "be used for all versions of a project." msgstr "" -#: ../source/specifications/version-specifiers.rst:693 +#: ../source/specifications/version-specifiers.rst:695 msgid "" "Due to the above, this specification MUST be used for all versions of " "metadata and supersedes :pep:`386` even for metadata v1.2. Tools SHOULD " @@ -16983,17 +16875,17 @@ msgid "" "available." msgstr "" -#: ../source/specifications/version-specifiers.rst:699 +#: ../source/specifications/version-specifiers.rst:701 msgid "" "Distribution users may wish to explicitly remove non-compliant versions from " "any private package indexes they control." msgstr "" -#: ../source/specifications/version-specifiers.rst:704 +#: ../source/specifications/version-specifiers.rst:706 msgid "Compatibility with other version schemes" msgstr "" -#: ../source/specifications/version-specifiers.rst:706 +#: ../source/specifications/version-specifiers.rst:708 msgid "" "Some projects may choose to use a version scheme which requires translation " "in order to comply with the public version scheme defined in this " @@ -17002,18 +16894,18 @@ msgid "" "field." msgstr "" -#: ../source/specifications/version-specifiers.rst:711 +#: ../source/specifications/version-specifiers.rst:713 msgid "" "This allows automated distribution tools to provide consistently correct " "ordering of published releases, while still allowing developers to use the " "internal versioning scheme they prefer for their projects." msgstr "" -#: ../source/specifications/version-specifiers.rst:717 +#: ../source/specifications/version-specifiers.rst:719 msgid "Semantic versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:719 +#: ../source/specifications/version-specifiers.rst:721 msgid "" "`Semantic versioning`_ is a popular version identification scheme that is " "more prescriptive than this specification regarding the significance of " @@ -17024,7 +16916,7 @@ msgid "" "on." msgstr "" -#: ../source/specifications/version-specifiers.rst:726 +#: ../source/specifications/version-specifiers.rst:728 msgid "" "The \"Major.Minor.Patch\" (described in this specification as \"major.minor." "micro\") aspects of semantic versioning (clauses 1-8 in the 2.0.0 " @@ -17032,30 +16924,30 @@ msgid "" "specification, and abiding by these aspects is encouraged." msgstr "" -#: ../source/specifications/version-specifiers.rst:731 +#: ../source/specifications/version-specifiers.rst:733 msgid "" "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " "sign (builds - clause 11) are *not* compatible with this specification and " "are not permitted in the public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:735 +#: ../source/specifications/version-specifiers.rst:737 msgid "" "One possible mechanism to translate such semantic versioning based source " "labels to compatible public versions is to use the ``.devN`` suffix to " "specify the appropriate version order." msgstr "" -#: ../source/specifications/version-specifiers.rst:739 +#: ../source/specifications/version-specifiers.rst:741 msgid "" "Specific build information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:745 +#: ../source/specifications/version-specifiers.rst:747 msgid "DVCS based version labels" msgstr "" -#: ../source/specifications/version-specifiers.rst:747 +#: ../source/specifications/version-specifiers.rst:749 msgid "" "Many build tools integrate with distributed version control systems like Git " "and Mercurial in order to add an identifying hash to the version identifier. " @@ -17063,30 +16955,30 @@ msgid "" "public version field." msgstr "" -#: ../source/specifications/version-specifiers.rst:752 +#: ../source/specifications/version-specifiers.rst:754 msgid "" "As with semantic versioning, the public ``.devN`` suffix may be used to " "uniquely identify such releases for publication, while the original DVCS " "based label can be stored in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:756 +#: ../source/specifications/version-specifiers.rst:758 msgid "" "Identifying hash information may also be included in local version labels." msgstr "" -#: ../source/specifications/version-specifiers.rst:760 +#: ../source/specifications/version-specifiers.rst:762 msgid "Olson database versioning" msgstr "" -#: ../source/specifications/version-specifiers.rst:762 +#: ../source/specifications/version-specifiers.rst:764 msgid "" "The ``pytz`` project inherits its versioning scheme from the corresponding " "Olson timezone database versioning scheme: the year followed by a lowercase " "character indicating the version of the database within that year." msgstr "" -#: ../source/specifications/version-specifiers.rst:766 +#: ../source/specifications/version-specifiers.rst:768 msgid "" "This can be translated to a compliant public version identifier as ``." "``, where the serial starts at zero or one (for the 'a' " @@ -17094,60 +16986,60 @@ msgid "" "year." msgstr "" -#: ../source/specifications/version-specifiers.rst:771 +#: ../source/specifications/version-specifiers.rst:773 msgid "" "As with other translated version identifiers, the corresponding Olson " "database version could be recorded in the project metadata." msgstr "" -#: ../source/specifications/version-specifiers.rst:778 +#: ../source/specifications/version-specifiers.rst:780 msgid "" "A version specifier consists of a series of version clauses, separated by " "commas. For example::" msgstr "" -#: ../source/specifications/version-specifiers.rst:783 +#: ../source/specifications/version-specifiers.rst:785 msgid "The comparison operator determines the kind of version clause:" msgstr "" -#: ../source/specifications/version-specifiers.rst:785 +#: ../source/specifications/version-specifiers.rst:787 msgid "``~=``: `Compatible release`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:786 +#: ../source/specifications/version-specifiers.rst:788 msgid "``==``: `Version matching`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:787 +#: ../source/specifications/version-specifiers.rst:789 msgid "``!=``: `Version exclusion`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:788 +#: ../source/specifications/version-specifiers.rst:790 msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:789 +#: ../source/specifications/version-specifiers.rst:791 msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" msgstr "" -#: ../source/specifications/version-specifiers.rst:790 +#: ../source/specifications/version-specifiers.rst:792 msgid "``===``: `Arbitrary equality`_ clause." msgstr "" -#: ../source/specifications/version-specifiers.rst:792 +#: ../source/specifications/version-specifiers.rst:794 msgid "" "The comma (\",\") is equivalent to a logical **and** operator: a candidate " "version must match all given version clauses in order to match the specifier " "as a whole." msgstr "" -#: ../source/specifications/version-specifiers.rst:796 +#: ../source/specifications/version-specifiers.rst:798 msgid "" "Whitespace between a conditional operator and the following version " "identifier is optional, as is the whitespace around the commas." msgstr "" -#: ../source/specifications/version-specifiers.rst:799 +#: ../source/specifications/version-specifiers.rst:801 msgid "" "When multiple candidate versions match a version specifier, the preferred " "version SHOULD be the latest version as determined by the consistent " @@ -17156,79 +17048,79 @@ msgid "" "in `Handling of pre-releases`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:805 +#: ../source/specifications/version-specifiers.rst:807 msgid "" "Except where specifically noted below, local version identifiers MUST NOT be " "permitted in version specifiers, and local version labels MUST be ignored " "entirely when checking if candidate versions match a given version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:814 +#: ../source/specifications/version-specifiers.rst:816 msgid "Compatible release" msgstr "" -#: ../source/specifications/version-specifiers.rst:816 +#: ../source/specifications/version-specifiers.rst:818 msgid "" "A compatible release clause consists of the compatible release operator " "``~=`` and a version identifier. It matches any candidate version that is " "expected to be compatible with the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:820 +#: ../source/specifications/version-specifiers.rst:822 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_. Local version identifiers are NOT permitted in this " "version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:824 +#: ../source/specifications/version-specifiers.rst:826 msgid "" "For a given release identifier ``V.N``, the compatible release clause is " "approximately equivalent to the pair of comparison clauses::" msgstr "" -#: ../source/specifications/version-specifiers.rst:829 +#: ../source/specifications/version-specifiers.rst:831 msgid "" "This operator MUST NOT be used with a single segment version number such as " "``~=1``." msgstr "" -#: ../source/specifications/version-specifiers.rst:832 +#: ../source/specifications/version-specifiers.rst:834 msgid "For example, the following groups of version clauses are equivalent::" msgstr "" -#: ../source/specifications/version-specifiers.rst:840 +#: ../source/specifications/version-specifiers.rst:842 msgid "" "If a pre-release, post-release or developmental release is named in a " "compatible release clause as ``V.N.suffix``, then the suffix is ignored when " "determining the required prefix match::" msgstr "" -#: ../source/specifications/version-specifiers.rst:850 +#: ../source/specifications/version-specifiers.rst:852 msgid "" "The padding rules for release segment comparisons means that the assumed " "degree of forward compatibility in a compatible release clause can be " "controlled by appending additional zeros to the version specifier::" msgstr "" -#: ../source/specifications/version-specifiers.rst:862 +#: ../source/specifications/version-specifiers.rst:864 msgid "Version matching" msgstr "" -#: ../source/specifications/version-specifiers.rst:864 +#: ../source/specifications/version-specifiers.rst:866 msgid "" "A version matching clause includes the version matching operator ``==`` and " "a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:867 +#: ../source/specifications/version-specifiers.rst:869 msgid "" "The specified version identifier must be in the standard format described in " "`Version scheme`_, but a trailing ``.*`` is permitted on public version " "identifiers as described below." msgstr "" -#: ../source/specifications/version-specifiers.rst:871 +#: ../source/specifications/version-specifiers.rst:873 msgid "" "By default, the version matching operator is based on a strict equality " "comparison: the specified version must be exactly the same as the requested " @@ -17237,7 +17129,7 @@ msgid "" "length." msgstr "" -#: ../source/specifications/version-specifiers.rst:877 +#: ../source/specifications/version-specifiers.rst:879 msgid "" "Whether or not strict version matching is appropriate depends on the " "specific use case for the version specifier. Automated tools SHOULD at least " @@ -17245,31 +17137,31 @@ msgid "" "used inappropriately." msgstr "" -#: ../source/specifications/version-specifiers.rst:882 +#: ../source/specifications/version-specifiers.rst:884 msgid "" "Prefix matching may be requested instead of strict comparison, by appending " "a trailing ``.*`` to the version identifier in the version matching clause. " "This means that additional trailing segments will be ignored when " "determining whether or not a version identifier matches the clause. If the " -"specified version includes only a release segment, than trailing components " +"specified version includes only a release segment, then trailing components " "(or the lack thereof) in the release segment are also ignored." msgstr "" -#: ../source/specifications/version-specifiers.rst:889 -#: ../source/specifications/version-specifiers.rst:950 +#: ../source/specifications/version-specifiers.rst:891 +#: ../source/specifications/version-specifiers.rst:952 msgid "" "For example, given the version ``1.1.post1``, the following clauses would " "match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:896 +#: ../source/specifications/version-specifiers.rst:898 msgid "" "For purposes of prefix matching, the pre-release segment is considered to " "have an implied preceding ``.``, so given the version ``1.1a1``, the " "following clauses would match or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:904 +#: ../source/specifications/version-specifiers.rst:906 msgid "" "An exact match is also considered a prefix match (this interpretation is " "implied by the usual zero padding rules for the release segment of version " @@ -17277,7 +17169,7 @@ msgid "" "or not as shown::" msgstr "" -#: ../source/specifications/version-specifiers.rst:916 +#: ../source/specifications/version-specifiers.rst:918 msgid "" "It is invalid to have a prefix match containing a development or local " "release such as ``1.0.dev1.*`` or ``1.0+foo1.*``. If present, the " @@ -17286,7 +17178,7 @@ msgid "" "either in a prefix match wouldn't make any sense." msgstr "" -#: ../source/specifications/version-specifiers.rst:922 +#: ../source/specifications/version-specifiers.rst:924 msgid "" "The use of ``==`` (without at least the wildcard suffix) when defining " "dependencies for published distributions is strongly discouraged as it " @@ -17296,14 +17188,14 @@ msgid "" "distribution index." msgstr "" -#: ../source/specifications/version-specifiers.rst:929 +#: ../source/specifications/version-specifiers.rst:931 msgid "" "If the specified version identifier is a public version identifier (no local " "version label), then the local version label of any candidate versions MUST " "be ignored when matching versions." msgstr "" -#: ../source/specifications/version-specifiers.rst:933 +#: ../source/specifications/version-specifiers.rst:935 msgid "" "If the specified version identifier is a local version identifier, then the " "local version labels of candidate versions MUST be considered when matching " @@ -17312,29 +17204,29 @@ msgid "" "strict string equality comparison." msgstr "" -#: ../source/specifications/version-specifiers.rst:941 +#: ../source/specifications/version-specifiers.rst:943 #, fuzzy msgid "Version exclusion" msgstr "翻譯" -#: ../source/specifications/version-specifiers.rst:943 +#: ../source/specifications/version-specifiers.rst:945 msgid "" "A version exclusion clause includes the version exclusion operator ``!=`` " "and a version identifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:946 +#: ../source/specifications/version-specifiers.rst:948 msgid "" "The allowed version identifiers and comparison semantics are the same as " "those of the `Version matching`_ operator, except that the sense of any " "match is inverted." msgstr "" -#: ../source/specifications/version-specifiers.rst:959 +#: ../source/specifications/version-specifiers.rst:961 msgid "Inclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:961 +#: ../source/specifications/version-specifiers.rst:963 msgid "" "An inclusive ordered comparison clause includes a comparison operator and a " "version identifier, and will match any version where the comparison is " @@ -17343,27 +17235,27 @@ msgid "" "`Version scheme`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:967 +#: ../source/specifications/version-specifiers.rst:969 msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." msgstr "" -#: ../source/specifications/version-specifiers.rst:969 -#: ../source/specifications/version-specifiers.rst:999 +#: ../source/specifications/version-specifiers.rst:971 +#: ../source/specifications/version-specifiers.rst:1001 msgid "" "As with version matching, the release segment is zero padded as necessary to " "ensure the release segments are compared with the same length." msgstr "" -#: ../source/specifications/version-specifiers.rst:972 -#: ../source/specifications/version-specifiers.rst:1002 +#: ../source/specifications/version-specifiers.rst:974 +#: ../source/specifications/version-specifiers.rst:1004 msgid "Local version identifiers are NOT permitted in this version specifier." msgstr "" -#: ../source/specifications/version-specifiers.rst:976 +#: ../source/specifications/version-specifiers.rst:978 msgid "Exclusive ordered comparison" msgstr "" -#: ../source/specifications/version-specifiers.rst:978 +#: ../source/specifications/version-specifiers.rst:980 msgid "" "The exclusive ordered comparisons ``>`` and ``<`` are similar to the " "inclusive ordered comparisons in that they rely on the relative position of " @@ -17373,7 +17265,7 @@ msgid "" "specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:984 +#: ../source/specifications/version-specifiers.rst:986 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release of " "the given version unless ``V`` itself is a post release. You may mandate " @@ -17383,13 +17275,13 @@ msgid "" "and ``1.7.0.post3`` but not ``1.7.0``." msgstr "" -#: ../source/specifications/version-specifiers.rst:991 +#: ../source/specifications/version-specifiers.rst:993 msgid "" "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " "of the specified version." msgstr "" -#: ../source/specifications/version-specifiers.rst:994 +#: ../source/specifications/version-specifiers.rst:996 msgid "" "The exclusive ordered comparison ``=`` entry as part " "of the URL fragment." msgstr "" -#: ../source/specifications/version-specifiers.rst:1123 +#: ../source/specifications/version-specifiers.rst:1125 msgid "" "For version control references, the ``VCS+protocol`` scheme SHOULD be used " "to identify both the version control system and the secure transport, and a " @@ -17608,7 +17500,7 @@ msgid "" "systems that do not provide hash based commit identifiers." msgstr "" -#: ../source/specifications/version-specifiers.rst:1129 +#: ../source/specifications/version-specifiers.rst:1131 msgid "" "To handle version control systems that do not support including commit or " "tag references directly in the URL, that information may be appended to the " @@ -17616,7 +17508,7 @@ msgid "" "notation." msgstr "" -#: ../source/specifications/version-specifiers.rst:1136 +#: ../source/specifications/version-specifiers.rst:1138 msgid "" "This isn't *quite* the same as the existing VCS reference notation supported " "by pip. Firstly, the distribution name is moved in front rather than " @@ -17627,15 +17519,15 @@ msgid "" "*hash*, less so)." msgstr "" -#: ../source/specifications/version-specifiers.rst:1144 +#: ../source/specifications/version-specifiers.rst:1146 msgid "Remote URL examples::" msgstr "" -#: ../source/specifications/version-specifiers.rst:1152 +#: ../source/specifications/version-specifiers.rst:1154 msgid "File URLs" msgstr "" -#: ../source/specifications/version-specifiers.rst:1154 +#: ../source/specifications/version-specifiers.rst:1156 msgid "" "File URLs take the form of ``file:///``. If the ```` is " "omitted it is assumed to be ``localhost`` and even if the ```` is " @@ -17643,7 +17535,7 @@ msgid "" "file path on the filesystem that is to be accessed." msgstr "" -#: ../source/specifications/version-specifiers.rst:1159 +#: ../source/specifications/version-specifiers.rst:1161 msgid "" "On the various \\*nix operating systems the only allowed values for " "```` is for it to be omitted, ``localhost``, or another FQDN that the " @@ -17651,7 +17543,7 @@ msgid "" "``file://`` scheme can only be used to access paths on the local machine." msgstr "" -#: ../source/specifications/version-specifiers.rst:1164 +#: ../source/specifications/version-specifiers.rst:1166 msgid "" "On Windows the file format should include the drive letter if applicable as " "part of the ```` (e.g. ``file:///c:/path/to/a/file``). Unlike \\*nix " @@ -17663,43 +17555,43 @@ msgid "" "b/ie/archive/2006/12/06/file-uris-in-windows.aspx>`_." msgstr "" -#: ../source/specifications/version-specifiers.rst:1175 +#: ../source/specifications/version-specifiers.rst:1177 msgid "Summary of differences from pkg_resources.parse_version" msgstr "" -#: ../source/specifications/version-specifiers.rst:1177 +#: ../source/specifications/version-specifiers.rst:1179 msgid "" "Note: this comparison is to ``pkg_resourses.parse_version`` as it existed at " "the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " "and later versions adopted the behaviour described here." msgstr "" -#: ../source/specifications/version-specifiers.rst:1181 +#: ../source/specifications/version-specifiers.rst:1183 msgid "" "Local versions sort differently, this specification requires that they sort " "as greater than the same version without a local version, whereas " "``pkg_resources.parse_version`` considers it a pre-release marker." msgstr "" -#: ../source/specifications/version-specifiers.rst:1185 +#: ../source/specifications/version-specifiers.rst:1187 msgid "" "This specification purposely restricts the syntax which constitutes a valid " "version while ``pkg_resources.parse_version`` attempts to provide some " "meaning from *any* arbitrary string." msgstr "" -#: ../source/specifications/version-specifiers.rst:1189 +#: ../source/specifications/version-specifiers.rst:1191 msgid "" "``pkg_resources.parse_version`` allows arbitrarily deeply nested version " "signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " "only a single use of each type and they must exist in a certain order." msgstr "" -#: ../source/specifications/version-specifiers.rst:1198 +#: ../source/specifications/version-specifiers.rst:1200 msgid "Appendix: Parsing version strings with regular expressions" msgstr "" -#: ../source/specifications/version-specifiers.rst:1200 +#: ../source/specifications/version-specifiers.rst:1202 msgid "" "As noted earlier in the :ref:`public-version-identifiers` section, published " "version identifiers SHOULD use the canonical format. This section provides " @@ -17708,20 +17600,20 @@ msgid "" "normalization." msgstr "" -#: ../source/specifications/version-specifiers.rst:1206 +#: ../source/specifications/version-specifiers.rst:1208 msgid "" "To test whether a version identifier is in the canonical format, you can use " -"the following function::" +"the following function:" msgstr "" -#: ../source/specifications/version-specifiers.rst:1213 +#: ../source/specifications/version-specifiers.rst:1217 msgid "" "To extract the components of a version identifier, use the following regular " "expression (as defined by the `packaging `_ project)::" +"packaging>`_ project):" msgstr "" -#: ../source/specifications/version-specifiers.rst:1258 +#: ../source/specifications/version-specifiers.rst:1264 msgid "" "This specification was originally approved as :pep:`440`, addressing several " "limitations of the previous attempt at standardized versioning, as described " @@ -19028,28 +18920,32 @@ msgid "" "are some things you can do:" msgstr "此時，如果您想閱讀有關打包 Python 庫的更多信息，您可以執行以下操作：" -#: ../source/tutorials/packaging-projects.rst:535 +#: ../source/tutorials/packaging-projects.rst:532 msgid "" -"Consider packaging tools that provide a single command-line interface for " -"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" -"`pdm`, and :ref:`poetry`." +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." msgstr "" -#: ../source/tutorials/packaging-projects.rst:538 +#: ../source/tutorials/packaging-projects.rst:536 msgid "" -"Read :pep:`517` and :pep:`518` for background and details on build tool " -"configuration." +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." msgstr "" #: ../source/tutorials/packaging-projects.rst:539 -msgid "Read about :doc:`/guides/packaging-binary-extensions`." -msgstr "閱讀 :doc:`/guides/packaging-binary-extensions`。" +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:" +"`pdm`, and :ref:`poetry`." +msgstr "" -#: ../source/tutorials/packaging-projects.rst:545 +#: ../source/tutorials/packaging-projects.rst:547 msgid "Notes" msgstr "" -#: ../source/tutorials/packaging-projects.rst:547 +#: ../source/tutorials/packaging-projects.rst:549 msgid "" "Technically, you can also create Python packages without an ``__init__.py`` " "file, but those are called :doc:`namespace packages